> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools.md) 教程，其中介绍了 XBOX PC Toolbox 应用、`wdRemote` 与 `wdEndpoint` 命令行工具，以及 Visual Studio 远程调试器。

## 快速开始

> **[XBOX PC Remote Tools 概览](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools.md)**
>
> 在远程 Windows 设备上预配、部署、启动、调试与迭代。

> **[快速开始](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools/quickstart.md)**
>
> 安装 XBOX PC Toolbox 应用并将你的开发设备与目标设备完成配对。

> **[wdRemote 命令行工具](https://docs.xbox.com/zh-CN/tools/tools-pc/commandlinetools/gr-wdRemote.md)**
>
> 远程迭代工作流的命令行控制。

> **[常见问题与故障排查](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools/faq.md)**
>
> 常见问题、已知问题与解决方法。

## 概述

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](https://docs.xbox.com/zh-CN/tools/tools-pc/xboxpctoolbox/xboxpctoolbox.md) 应用完成预配，从而实现配对与相互信任。
* **wdEndpoint：** 远程设备上必须安装并运行 `wdEndpoint`。[XBOX PC Toolbox](https://docs.xbox.com/zh-CN/tools/tools-pc/xboxpctoolbox/xboxpctoolbox.md) 的设置流程会默认安装并配置 `wdEndpoint`。
* **头文件与库：** 包含 `WdRemoteIteration.h` 并链接 `wdremoteapi.lib`。

## 函数

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

## 结构体

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

## 枚举

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

## 回调

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

## 线程模型

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

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

## 重试行为

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

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

## 取消

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

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

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

## 公共根路径

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

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

## 错误码

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

## 版本、维护与分发

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 |

## 概念文档

> **[XBOX PC Remote Tools](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools.md)**
>
> 设置远程 Windows 设备，并使用 XBOX PC Remote Tools 进行部署、启动、调试与迭代。

* [XBOX PC Remote Tools 发布说明（2026 年 3 月）](https://docs.xbox.com/zh-CN/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603.md)

## 另请参阅

* [WdRemoteCopy](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdremotecopy.md)
* [WdCancelRemoteCopy](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdcancelremotecopy.md)
* [WdCreateCancellationHandle](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdcreatecancellationhandle.md)
* [WdLaunchRemoteGame](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdlaunchremotegame.md)
* [WdRegisterRemoteXboxGame](https://docs.xbox.com/zh-CN/reference/remoting/functions/wdregisterremotexboxgame.md)


## Related topics

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