> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XBOX PC Remote Iteration API

> XBOX PC Remote Iteration API 参考：提供在远程 Windows 开发设备上复制文件、启动、恢复与终止游戏的函数集合。

# XBOX PC Remote Iteration API

提供用于在远程 Windows 设备上复制文件、启动、恢复与终止游戏的函数。

<Note>
  正在寻找基于应用的工作流？请参见 [XBOX PC Remote Tools](/tools/tools-pc/xbox-pc-remote-tools) 教程，其中介绍了 XBOX PC Toolbox 应用、`wdRemote` 与 `wdEndpoint` 命令行工具，以及 Visual Studio 远程调试器。
</Note>

## 快速开始

<CardGroup cols={2}>
  <Card title="XBOX PC Remote Tools 概览" icon="network-wired" href="/tools/tools-pc/xbox-pc-remote-tools">
    在远程 Windows 设备上预配、部署、启动、调试与迭代。
  </Card>

  <Card title="快速开始" icon="rocket" href="/tools/tools-pc/xbox-pc-remote-tools/quickstart">
    安装 XBOX PC Toolbox 应用并将你的开发设备与目标设备完成配对。
  </Card>

  <Card title="wdRemote 命令行工具" icon="terminal" href="/tools/tools-pc/commandlinetools/gr-wdRemote">
    远程迭代工作流的命令行控制。
  </Card>

  <Card title="常见问题与故障排查" icon="circle-question" href="/tools/tools-pc/xbox-pc-remote-tools/faq">
    常见问题、已知问题与解决方法。
  </Card>
</CardGroup>

## 概述

XBOX PC Remote Iteration API 支持面向远程 Windows 设备的 PC 端开发工作流。它提供了一组 C 函数，可在本地 PC 与远程设备之间传输游戏文件、在远程设备上启动与管理游戏进程，以及为远程执行注册游戏。该 API 专为游戏开发过程中的紧凑迭代循环而设计，让你可以在本地构建，并在远程硬件上部署与测试，无需手动管理文件。

## 何时使用

* 在开发过程中，将本地 PC 上的游戏构建部署到远程 Windows 设备。
* 将更新过的文件（增量复制）复制到远程设备，以最小化迭代构建中的传输时间。
* 从你的开发 PC 上启动、挂起、恢复与终止远程设备上的游戏进程。
* 在面向远程 Windows 设备的持续集成流水线中，自动化构建-部署-测试工作流。
* 用于构建或集成到自定义工作室工具中，以便在本地或测试实验室中向远程 Windows 设备部署。

## 不应使用的场景

* 请勿使用此 API 将游戏零售或生产部署到最终用户主机上。
* 请勿使用此 API 在两台远程设备之间传输文件；其中一端必须是本地 PC。
* 如果远程设备尚未配对并配置为远程开发使用，请勿使用此 API。

## 前提条件

* **NuGet 包：** [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) 版本 0.1.0-preview\.26.3.6001 或更高。
* **设备配对：** 本地 PC 与远程设备必须使用 [XBOX PC Toolbox](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 应用完成预配，从而实现配对与相互信任。
* **wdEndpoint：** 远程设备上必须安装并运行 `wdEndpoint`。[XBOX PC Toolbox](/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 的设置流程会默认安装并配置 `wdEndpoint`。
* **头文件与库：** 包含 `WdRemoteIteration.h` 并链接 `wdremoteapi.lib`。

## 函数

| 函数                                                                                           | 说明                    |
| -------------------------------------------------------------------------------------------- | --------------------- |
| [WdRemoteCopy](/reference/remoting/functions/wdremotecopy)                                   | 在本地 PC 与远程设备之间复制文件。   |
| [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)                       | 取消进行中的复制操作。           |
| [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)       | 创建用于取消复制操作的取消句柄。      |
| [WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle)         | 关闭取消句柄。               |
| [WdDuplicateCancellationHandle](/reference/remoting/functions/wdduplicatecancellationhandle) | 复制一个已存在的取消句柄。         |
| [WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame)                       | 在远程设备上启动一款游戏。         |
| [WdResumeRemoteGame](/reference/remoting/functions/wdresumeremotegame)                       | 在远程设备上恢复最近以挂起模式启动的游戏。 |
| [WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame)                 | 终止远程设备上最近启动的游戏。       |
| [WdRegisterRemoteXboxGame](/reference/remoting/functions/wdregisterremotexboxgame)           | 在远程设备上注册一款游戏。         |

## 结构体

| 结构体                                                                          | 说明                      |
| ---------------------------------------------------------------------------- | ----------------------- |
| [WdCopyFileProgressInfo](/reference/remoting/structs/wdcopyfileprogressinfo) | 包含复制操作过程中单个文件的进度信息。     |
| [WdCopyOperationSummary](/reference/remoting/structs/wdcopyoperationsummary) | 包含整个复制操作的汇总进度信息。        |
| [WdCopyOptions](/reference/remoting/structs/wdcopyoptions)                   | 指定复制操作的方向与模式。           |
| [WdCopyStatusCallbacks](/reference/remoting/structs/wdcopystatuscallbacks)   | 包含用于接收复制状态更新的回调函数指针与设置。 |
| [WdCopySearchOptions](/reference/remoting/structs/wdcopysearchoptions)       | 指定复制操作的文件与目录筛选模式。       |
| [WdCancellationHandle](/reference/remoting/structs/wdcancellationhandle)     | 用于取消进行中复制操作的不透明句柄。      |
| [WdLaunchOptions](/reference/remoting/structs/wdlaunchoptions)               | 指定在远程设备上启动游戏的选项。        |

## 枚举

| 枚举                                                                   | 说明                |
| -------------------------------------------------------------------- | ----------------- |
| [WdCopyDirection](/reference/remoting/enums/wdcopydirection)         | 指定复制操作的方向。        |
| [WdLaunchMode](/reference/remoting/enums/wdlaunchmode)               | 指定远程游戏的启动模式。      |
| [WdCopyErrorSeverity](/reference/remoting/enums/wdcopyerrorseverity) | 指定复制错误或警告消息的严重程度。 |

## 回调

| 回调                                                                                   | 说明                   |
| ------------------------------------------------------------------------------------ | -------------------- |
| [WdCopyFilesStatusCallback](/reference/remoting/callbacks/wdcopyfilesstatuscallback) | 用于在复制操作过程中报告文件复制进度。  |
| [WdCopyErrorCallback](/reference/remoting/callbacks/wdcopyerrorcallback)             | 用于在复制操作过程中报告错误与警告消息。 |

## 线程模型

XBOX PC Remote Iteration API 是为单线程复制操作设计的。以下规则适用：

* **一次仅执行一次复制。** 在任何给定时间，只能有一次 [WdRemoteCopy](/reference/remoting/functions/wdremotecopy) 调用处于活动状态，无论目标设备或目标路径为何。在另一次复制仍在进行时调用 `WdRemoteCopy` 会导致**未定义行为**。
* **复制期间可以安全调用其他函数。** 在复制进行过程中，可以从其他线程调用诸如 [WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame)、[WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame)、[WdResumeRemoteGame](/reference/remoting/functions/wdresumeremotegame) 与 [WdRegisterRemoteXboxGame](/reference/remoting/functions/wdregisterremotexboxgame) 等函数。
* **所有函数都是阻塞的。** API 中每个函数都会阻塞调用线程，直到操作完成或失败。特别是 `WdRemoteCopy`，可能会根据传输大小与网络状况阻塞较长时间。
* **取消操作是线程安全的。** [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) 可以从任意线程调用。如果多个线程同时尝试取消同一个操作，这些调用会在内部被序列化 —— 第一个成功，后续的调用会返回错误，因为已经没有可取消的内容。
* **调用之间不保留连接状态。** 每次 API 调用都会建立自己到远程设备的连接。不存在持久化会话 —— 例如，如果在 [WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame) 完成后连接断开，等到连通性恢复后你仍然可以调用 [WdTerminateRemoteGame](/reference/remoting/functions/wdterminateremotegame)。

## 重试行为

XBOX PC Remote Iteration API **不**会在 API 层面自动重试失败的操作。如果操作因网络中断或其他瞬时错误失败，调用方需要负责重试。

* **不自动重试。** 如果复制操作失败（例如由于网络连接丢失），`WdRemoteCopy` 会返回错误。调用方必须再次调用该函数以重试。
* **无可配置的超时。** `WdRemoteCopy` 不会对复制操作设置超时。它会持续传输，直到完成、发生错误或通过 [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy) 被取消。在网络状况较差时，传输可能会非常缓慢地进行，而不是失败。
* **失败时保留进度。** 在失败之前已经成功复制的文件仍然会保留在目标设备上。当调用方重试复制时，增量复制行为会确保只传输不完整或缺失的文件 —— 已经复制过的文件不会重新传输。
* **磁盘空间错误会被报告。** 如果目标设备在复制过程中磁盘空间用尽，操作会以错误结束，而不是挂起。
* **传输层的弹性。** 底层传输层会以透明方式处理低层次的数据包重传。轻微的网络波动（例如单个丢包）不会导致操作失败。但是，持续的连通性丢失最终会导致错误。
* **推荐的重试模式。** 在 `WdRemoteCopy` 失败后，只需使用相同的参数再次调用 `WdRemoteCopy`。增量复制行为通过只传输目标端缺失或不完整的文件，最大程度地减少了冗余工作。

## 取消

XBOX PC Remote Iteration API 为长时间运行的复制操作提供了基于句柄的取消模型。调用方需要负责句柄的生命周期：

1. 通过调用 [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle) 创建句柄。
2. 通过 `cancellationHandle` 参数将句柄传给 [WdRemoteCopy](/reference/remoting/functions/wdremotecopy)。
3. 从另一个线程使用该句柄调用 [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)，以取消进行中的复制。`WdCancelRemoteCopy` 是非阻塞的。取消信号发出后，`WdRemoteCopy` 会完成取消流程并返回 `S_OK`。
4. `WdRemoteCopy` 返回后，通过调用 [WdCloseCancellationHandle](/reference/remoting/functions/wdclosecancellationhandle) 关闭句柄。

如果多个组件需要引用同一个取消句柄，请使用 [WdDuplicateCancellationHandle](/reference/remoting/functions/wdduplicatecancellationhandle) 对其进行复制。每个副本都必须独立关闭。

## 公共根路径

公共根路径是远程设备上预先配置的、通常用于复制或启动游戏的已知位置。调用方无需指定完整的绝对路径，而是可以使用 [WdCopyOptions](/reference/remoting/structs/wdcopyoptions) 或 [WdLaunchOptions](/reference/remoting/structs/wdlaunchoptions) 中的 `commonRootAlias` 字段通过别名来引用这些位置。

如果 `destinationPath` 是绝对路径，`commonRootAlias` 会被忽略。当 `destinationPath` 是相对路径时，它会相对于别名标识的公共根路径进行解析。如果未指定别名，则使用默认的公共根路径位置。

## 错误码

要查看完整的 API 特定错误码列表，包括说明、根本原因与故障排查指南，请参见 [XBOX PC Remote Iteration API 错误码](/reference/remoting/error-codes)。

## 版本、维护与分发

Remote Iteration Tools (RIT) API 遵循 **Semantic Versioning 2.0.0**（`MAJOR.MINOR.PATCH`），围绕兼容性、升级与长期支持提供清晰的预期。所有公开的 RIT API 库都通过 **NuGet** 分发，从而支持标准的依赖管理与更新工作流。

### 版本模型

#### PATCH 版本

`PATCH` 更新用于修复缺陷并提升可靠性。这些更新**不**会改变 API 契约或运行时行为，可以安全地直接替换。升级到较新的 `PATCH` 版本不需要修改代码。

#### MINOR 版本

`MINOR` 更新以向后兼容的方式引入新 API 或演进现有功能。当某些 API 计划在未来变更或移除时，会明确标记为已弃用，从而给开发者留出迁移的时间。依赖更新会被审查，以确保在同一 `MAJOR` 版本内保持兼容。

#### MAJOR 版本

`MAJOR` 更新代表有意为之的破坏性变更。这些版本可能需要修改代码或更新依赖，并会附带清晰的迁移指南。升级到新的 `MAJOR` 版本被视为一次显式的、可选择的决策，需要配合正常的验证与发布周期。

### 维护与支持模型

RIT API 的 `MAJOR` 或 `MINOR` 版本一旦公开发布，就会进入一段活跃的维护期，目标支持窗口约为 **18 个月**。在这段时间内：

* `PATCH` 版本会获批发布，用于修复缺陷并提升受支持版本的可靠性。
* 随着新版本的发布、以及补丁与小版本变更对现有版本的改进和缺陷修复，可能有多个 `MAJOR` 与 `MINOR` 版本同时处于维护中。
* `PATCH` 版本**不**会延长 `MAJOR` 或 `MINOR` 版本的维护生命周期。
* 新特性只会在较新的 `MINOR` 或 `MAJOR` 版本中引入，不会向后移植。

维护窗口结束后，该版本将被停用，开发者需要迁移到较新的受支持 `MAJOR` 或 `MINOR` 版本。

### 升级预期

建议开发者在同一 `MAJOR` 版本内保持最新，及时采纳 `PATCH` 与 `MINOR` 更新。`MAJOR` 版本升级应当有计划地进行，并显式地进行验证，以确保与生产工作流的兼容性。

### API 与 wdEndpoint 版本兼容性

RIT API 客户端库与运行在远程设备上的 `wdEndpoint` 应始终保持在兼容的版本。较新的 API 版本搭配较旧的 `wdEndpoint` 可能会导致 `E_SERVERTOOOLD` 错误或意外行为。为保证行为正确、完整的向后兼容以及支持最新的 API 特性，建议在更新 API 客户端库时，同时更新所有远程设备上的 `wdEndpoint`。请查阅 NuGet 包的发布说明了解最低 `wdEndpoint` 版本要求。

## 要求

| 要求          | 值                                                                         |
| ----------- | ------------------------------------------------------------------------- |
| **头文件**     | WdRemoteIteration.h                                                       |
| **库**       | wdremoteapi.lib                                                           |
| **NuGet 包** | [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) |
| **支持的操作系统** | Windows 11 及更高版本                                                          |
| **支持的架构**   | x64、ARM64                                                                 |

## 概念文档

<Card title="XBOX PC Remote Tools" icon="network-wired" href="/tools/tools-pc/xbox-pc-remote-tools">
  设置远程 Windows 设备，并使用 XBOX PC Remote Tools 进行部署、启动、调试与迭代。
</Card>

* [XBOX PC Remote Tools 发布说明（2026 年 3 月）](/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603)

## 另请参阅

* [WdRemoteCopy](/reference/remoting/functions/wdremotecopy)
* [WdCancelRemoteCopy](/reference/remoting/functions/wdcancelremotecopy)
* [WdCreateCancellationHandle](/reference/remoting/functions/wdcreatecancellationhandle)
* [WdLaunchRemoteGame](/reference/remoting/functions/wdlaunchremotegame)
* [WdRegisterRemoteXboxGame](/reference/remoting/functions/wdregisterremotexboxgame)


## Related topics

- [XBOX PC Remote 工具:2026 年 3 月 (2603) 发行说明](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)
- [XBOX PC Remote Tools](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/index.md)
- [如何使用 XBOX PC Remote 工具](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/how-to-use-tools.md)
- [XBOX PC Remote 工具快速入门指南](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/quickstart.md)
- [XBOX PC Remote 工具:2026 年 5 月 (2605) 发行说明](/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2605.md)