XBOX PC Remote Iteration API
提供用于在远程 Windows 设备上复制文件、启动、恢复与终止游戏的函数。正在寻找基于应用的工作流？请参见 XBOX PC Remote Tools 教程，其中介绍了 XBOX PC Toolbox 应用、
wdRemote 与 wdEndpoint 命令行工具，以及 Visual Studio 远程调试器。快速开始
XBOX PC Remote Tools 概览
在远程 Windows 设备上预配、部署、启动、调试与迭代。
快速开始
安装 XBOX PC Toolbox 应用并将你的开发设备与目标设备完成配对。
wdRemote 命令行工具
远程迭代工作流的命令行控制。
常见问题与故障排查
常见问题、已知问题与解决方法。
概述
XBOX PC Remote Iteration API 支持面向远程 Windows 设备的 PC 端开发工作流。它提供了一组 C 函数，可在本地 PC 与远程设备之间传输游戏文件、在远程设备上启动与管理游戏进程，以及为远程执行注册游戏。该 API 专为游戏开发过程中的紧凑迭代循环而设计，让你可以在本地构建，并在远程硬件上部署与测试，无需手动管理文件。何时使用
- 在开发过程中，将本地 PC 上的游戏构建部署到远程 Windows 设备。
- 将更新过的文件（增量复制）复制到远程设备，以最小化迭代构建中的传输时间。
- 从你的开发 PC 上启动、挂起、恢复与终止远程设备上的游戏进程。
- 在面向远程 Windows 设备的持续集成流水线中，自动化构建-部署-测试工作流。
- 用于构建或集成到自定义工作室工具中，以便在本地或测试实验室中向远程 Windows 设备部署。
不应使用的场景
- 请勿使用此 API 将游戏零售或生产部署到最终用户主机上。
- 请勿使用此 API 在两台远程设备之间传输文件；其中一端必须是本地 PC。
- 如果远程设备尚未配对并配置为远程开发使用，请勿使用此 API。
前提条件
- NuGet 包： Microsoft.GDK.RemoteIterationClientApi 版本 0.1.0-preview.26.3.6001 或更高。
- 设备配对： 本地 PC 与远程设备必须使用 XBOX PC Toolbox 应用完成预配，从而实现配对与相互信任。
- wdEndpoint： 远程设备上必须安装并运行
wdEndpoint。XBOX PC Toolbox 的设置流程会默认安装并配置wdEndpoint。 - 头文件与库： 包含
WdRemoteIteration.h并链接wdremoteapi.lib。
函数
结构体
枚举
回调
线程模型
XBOX PC Remote Iteration API 是为单线程复制操作设计的。以下规则适用：- 一次仅执行一次复制。 在任何给定时间，只能有一次 WdRemoteCopy 调用处于活动状态，无论目标设备或目标路径为何。在另一次复制仍在进行时调用
WdRemoteCopy会导致未定义行为。 - 复制期间可以安全调用其他函数。 在复制进行过程中，可以从其他线程调用诸如 WdLaunchRemoteGame、WdTerminateRemoteGame、WdResumeRemoteGame 与 WdRegisterRemoteXboxGame 等函数。
- 所有函数都是阻塞的。 API 中每个函数都会阻塞调用线程，直到操作完成或失败。特别是
WdRemoteCopy，可能会根据传输大小与网络状况阻塞较长时间。 - 取消操作是线程安全的。 WdCancelRemoteCopy 可以从任意线程调用。如果多个线程同时尝试取消同一个操作，这些调用会在内部被序列化 —— 第一个成功，后续的调用会返回错误，因为已经没有可取消的内容。
- 调用之间不保留连接状态。 每次 API 调用都会建立自己到远程设备的连接。不存在持久化会话 —— 例如，如果在 WdLaunchRemoteGame 完成后连接断开，等到连通性恢复后你仍然可以调用 WdTerminateRemoteGame。
重试行为
XBOX PC Remote Iteration API 不会在 API 层面自动重试失败的操作。如果操作因网络中断或其他瞬时错误失败，调用方需要负责重试。- 不自动重试。 如果复制操作失败（例如由于网络连接丢失），
WdRemoteCopy会返回错误。调用方必须再次调用该函数以重试。 - 无可配置的超时。
WdRemoteCopy不会对复制操作设置超时。它会持续传输，直到完成、发生错误或通过 WdCancelRemoteCopy 被取消。在网络状况较差时，传输可能会非常缓慢地进行，而不是失败。 - 失败时保留进度。 在失败之前已经成功复制的文件仍然会保留在目标设备上。当调用方重试复制时，增量复制行为会确保只传输不完整或缺失的文件 —— 已经复制过的文件不会重新传输。
- 磁盘空间错误会被报告。 如果目标设备在复制过程中磁盘空间用尽，操作会以错误结束，而不是挂起。
- 传输层的弹性。 底层传输层会以透明方式处理低层次的数据包重传。轻微的网络波动（例如单个丢包）不会导致操作失败。但是，持续的连通性丢失最终会导致错误。
- 推荐的重试模式。 在
WdRemoteCopy失败后，只需使用相同的参数再次调用WdRemoteCopy。增量复制行为通过只传输目标端缺失或不完整的文件，最大程度地减少了冗余工作。
取消
XBOX PC Remote Iteration API 为长时间运行的复制操作提供了基于句柄的取消模型。调用方需要负责句柄的生命周期：- 通过调用 WdCreateCancellationHandle 创建句柄。
- 通过
cancellationHandle参数将句柄传给 WdRemoteCopy。 - 从另一个线程使用该句柄调用 WdCancelRemoteCopy，以取消进行中的复制。
WdCancelRemoteCopy是非阻塞的。取消信号发出后，WdRemoteCopy会完成取消流程并返回S_OK。 WdRemoteCopy返回后，通过调用 WdCloseCancellationHandle 关闭句柄。
公共根路径
公共根路径是远程设备上预先配置的、通常用于复制或启动游戏的已知位置。调用方无需指定完整的绝对路径，而是可以使用 WdCopyOptions 或 WdLaunchOptions 中的commonRootAlias 字段通过别名来引用这些位置。
如果 destinationPath 是绝对路径，commonRootAlias 会被忽略。当 destinationPath 是相对路径时，它会相对于别名标识的公共根路径进行解析。如果未指定别名，则使用默认的公共根路径位置。
错误码
要查看完整的 API 特定错误码列表，包括说明、根本原因与故障排查指南，请参见 XBOX PC Remote Iteration API 错误码。版本、维护与分发
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 版本要求。
要求
概念文档
XBOX PC Remote Tools
设置远程 Windows 设备，并使用 XBOX PC Remote Tools 进行部署、启动、调试与迭代。