> ## 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 型裝置上複製和刪除檔案，以及啟動、繼續和終止遊戲的函式。

## 概觀

XBOX PC Remote Iteration API 可啟用以遠端 Windows 裝置為目標的 PC 型開發工作流程。它提供一組 C 函式，用於在本機 PC 與遠端裝置之間傳輸遊戲檔案，以及在遠端裝置上啟動和管理遊戲處理程序。此 API 專為遊戲開發期間的緊密反覆運算循環而設計，可讓開發人員在本機建置，並在遠端硬體上部署和測試，無需手動管理檔案。

## API 可用性

本參考說明最新的 API。除非另有指定較新的版本，否則公開 API 宣告自 [RIT 0.0.8-Preview](/zh-TW/reference/remoting/release-versions#release-versions) (初始公開 API 版本) 起提供。

**推出版本**表示宣告新增的時間。**支援起始版本**表示已宣告的選項開始運作的時間。宣告的推出並不代表目前未使用的回呼或設定已實作。**變更歷程記錄**章節描述 API 宣告或行為的變更，而非文件的更正。

版本標籤使用 WinGet 版本。[發行版本表格](/zh-TW/reference/remoting/release-versions#release-versions)會將每個標籤對應到 API NuGet 套件和命令列工具版本。

## 使用時機

* 在開發期間將遊戲組建從本機 PC 部署到遠端 Windows 裝置。
* 將更新的檔案 (差異複製) 複製到遠端裝置，以在反覆建置期間將傳輸時間降到最低。
* 在部署新組建之前，從遠端裝置移除過時的組建輸出。
* 從開發 PC 在遠端裝置上啟動、暫停、繼續和終止遊戲處理程序。
* 在以遠端 Windows 裝置為目標的持續整合管線中，自動化建置-部署-測試工作流程。
* 建置或整合至自訂工作室工具，以在本機或測試實驗室中部署到遠端 Windows 裝置。

## 不應使用的時機

* 請勿使用此 API 將遊戲以零售或生產方式部署到終端使用者主機。
* 請勿使用此 API 在兩個遠端裝置之間傳輸檔案；其中一個端點必須是本機 PC。
* 如果遠端裝置尚未配對並設定為遠端開發，請勿使用此 API。

## 必要條件

* **NuGet 套件：** 基本 API 需要 [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) 0.1.0-preview\.26.3.6001 版或更新版本。較新的 API 和選項需要其參考頁面上所標示的版本。
* **裝置配對：** 本機 PC 與遠端裝置必須使用 [XBOX PC Toolbox](/zh-TW/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 應用程式佈建，以完成配對並相互信任。
* **wdEndpoint：** `wdEndpoint` 必須已安裝並在遠端裝置上執行。[XBOX PC Toolbox](/zh-TW/tools/tools-pc/xboxpctoolbox/xboxpctoolbox) 安裝程式預設會安裝並設定 `wdEndpoint`。
* **標頭和程式庫：** 包含 `WdRemoteIteration.h` 並連結 `wdremoteapi.lib`。

## 範例

[Remote Iteration Tools Sample](https://github.com/microsoft/Xbox-GDK-Samples/tree/main/Samples/Tools/RemoteIterationToolsSample) 是一個 C# WPF 應用程式，示範如何在遠端裝置上部署、啟動、繼續和終止遊戲，以及取消進行中的部署。

## 函式

| 函式 | 描述 |
| - | - |
| [WdRemoteCopy](/zh-TW/reference/remoting/functions/wdremotecopy) | 在本機 PC 與遠端裝置之間複製檔案。 |
| [WdCancelRemoteCopy](/zh-TW/reference/remoting/functions/wdcancelremotecopy) | 取消進行中的複製作業。 |
| [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle) | 建立用於取消複製或刪除作業的取消控制代碼。 |
| [WdCloseCancellationHandle](/zh-TW/reference/remoting/functions/wdclosecancellationhandle) | 關閉取消控制代碼。 |
| [WdDuplicateCancellationHandle](/zh-TW/reference/remoting/functions/wdduplicatecancellationhandle) | 複製現有的取消控制代碼。 |
| [WdLaunchRemoteGame](/zh-TW/reference/remoting/functions/wdlaunchremotegame) | 在遠端裝置上啟動遊戲。 |
| [WdResumeRemoteGame](/zh-TW/reference/remoting/functions/wdresumeremotegame) | 繼續執行遠端裝置上最後一個以暫停模式啟動的遊戲。 |
| [WdTerminateRemoteGame](/zh-TW/reference/remoting/functions/wdterminateremotegame) | 終止遠端裝置上最後一個啟動的遊戲。 |
| [WdRegisterRemoteXboxGame](/zh-TW/reference/remoting/functions/wdregisterremotexboxgame) | 解析並驗證遠端資料夾路徑；不執行平台遊戲註冊。 |
| [WdDeleteRemoteFiles](/zh-TW/reference/remoting/functions/wddeleteremotefiles) | 盡力刪除遠端裝置上的檔案和目錄。 |
| [WdCancelRemoteDelete](/zh-TW/reference/remoting/functions/wdcancelremotedelete) | 發出訊號以取消用戶端對刪除作業的等待。 |

## 結構

| 結構 | 描述 |
| - | - |
| [WdCopyFileProgressInfo](/zh-TW/reference/remoting/structs/wdcopyfileprogressinfo) | 包含複製作業期間個別檔案的進度資訊。 |
| [WdCopyOperationSummary](/zh-TW/reference/remoting/structs/wdcopyoperationsummary) | 包含整體複製作業的摘要進度資訊。 |
| [WdCopyOptions](/zh-TW/reference/remoting/structs/wdcopyoptions) | 指定複製作業的方向和通用根目錄別名。 |
| [WdCopyStatusCallbacks](/zh-TW/reference/remoting/structs/wdcopystatuscallbacks) | 包含用於接收複製狀態更新的回呼函式指標和設定。 |
| [WdCopySearchOptions](/zh-TW/reference/remoting/structs/wdcopysearchoptions) | 指定複製作業的檔案和目錄篩選模式。 |
| [WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle) | 用來取消進行中之複製或刪除作業的不透明控制代碼。 |
| [WdLaunchOptions](/zh-TW/reference/remoting/structs/wdlaunchoptions) | 指定在遠端裝置上啟動遊戲的選項。 |
| [WdDeleteFileProgressInfo](/zh-TW/reference/remoting/structs/wddeletefileprogressinfo) | 目前未使用；不會產生個別項目的刪除進度資料。 |
| [WdDeleteOperationSummary](/zh-TW/reference/remoting/structs/wddeleteoperationsummary) | 目前未使用；不會產生刪除進度摘要。 |
| [WdDeleteOptions](/zh-TW/reference/remoting/structs/wddeleteoptions) | 指定遠端裝置上刪除作業的選項。 |
| [WdDeleteStatusCallbacks](/zh-TW/reference/remoting/structs/wddeletestatuscallbacks) | 包含目前會被忽略的回呼函式指標和設定。 |
| [WdDeleteSearchOptions](/zh-TW/reference/remoting/structs/wddeletesearchoptions) | 指定刪除作業的檔案和目錄篩選模式。 |

## 列舉

| 列舉 | 描述 |
| - | - |
| [WdCopyDirection](/zh-TW/reference/remoting/enums/wdcopydirection) | 指定複製作業的方向。 |
| [WdLaunchMode](/zh-TW/reference/remoting/enums/wdlaunchmode) | 指定遠端遊戲的啟動模式。 |
| [WdCopyErrorSeverity](/zh-TW/reference/remoting/enums/wdcopyerrorseverity) | 指定複製錯誤或警告訊息的嚴重性。 |

## 回呼

| 回呼 | 描述 |
| - | - |
| [WdCopyFilesStatusCallback](/zh-TW/reference/remoting/callbacks/wdcopyfilesstatuscallback) | 在複製作業期間呼叫以回報檔案複製進度。 |
| [WdCopyErrorCallback](/zh-TW/reference/remoting/callbacks/wdcopyerrorcallback) | 在複製作業期間呼叫以回報錯誤和警告訊息。 |
| [WdDeleteProgressCallback](/zh-TW/reference/remoting/callbacks/wddeleteprogresscallback) | 目前未使用；`WdDeleteRemoteFiles` 永遠不會叫用。 |
| [WdDeleteErrorCallback](/zh-TW/reference/remoting/callbacks/wddeleteerrorcallback) | 目前未使用；`WdDeleteRemoteFiles` 永遠不會叫用。 |

## 執行緒模型

XBOX PC Remote Iteration API 是針對單一執行緒的複製作業所設計。適用下列規則：

* **一次一個複製作業。** 無論目標裝置或目的地路徑為何，任何時候都只能有一個 [WdRemoteCopy](/zh-TW/reference/remoting/functions/wdremotecopy) 呼叫處於作用中狀態。在另一個複製作業進行中時呼叫 `WdRemoteCopy`，會導致**未定義的行為**。
* **複製期間可安全使用其他函式。** 在複製進行中時，可以從其他執行緒呼叫 [WdLaunchRemoteGame](/zh-TW/reference/remoting/functions/wdlaunchremotegame)、[WdTerminateRemoteGame](/zh-TW/reference/remoting/functions/wdterminateremotegame)、[WdResumeRemoteGame](/zh-TW/reference/remoting/functions/wdresumeremotegame) 和 [WdRegisterRemoteXboxGame](/zh-TW/reference/remoting/functions/wdregisterremotexboxgame) 等函式。
* **遠端作業會封鎖。** `WdRemoteCopy` 和 `WdDeleteRemoteFiles` 等函式會封鎖並等待作業結果、錯誤或觀察到的取消。`WdCancelRemoteCopy` 和 `WdCancelRemoteDelete` 不會封鎖。
* **取消是執行緒安全的。** 可以從另一個執行緒呼叫 [WdCancelRemoteCopy](/zh-TW/reference/remoting/functions/wdcancelremotecopy) 和 [WdCancelRemoteDelete](/zh-TW/reference/remoting/functions/wdcancelremotedelete) 來發出取消訊號。
* **遠端作業之間沒有連線狀態。** 每個遠端作業呼叫都會建立自己與遠端裝置的連線。沒有持續性工作階段；例如，如果在 [WdLaunchRemoteGame](/zh-TW/reference/remoting/functions/wdlaunchremotegame) 完成之後連線中斷，在恢復連線後仍可呼叫 [WdTerminateRemoteGame](/zh-TW/reference/remoting/functions/wdterminateremotegame)。

## 重試行為

XBOX PC Remote Iteration API **不會**在 API 層級自動重試失敗的作業。如果作業因網路中斷或其他暫時性錯誤而失敗，由呼叫端負責重試。

* **不會自動重試。** 如果複製作業失敗 (例如因為失去網路連線)，`WdRemoteCopy` 會傳回錯誤。呼叫端必須重新叫用該函式以重試。
* **沒有可設定的逾時。** `WdRemoteCopy` 不會對複製作業施加逾時。它會持續傳輸，直到完成、發生錯誤，或透過 [WdCancelRemoteCopy](/zh-TW/reference/remoting/functions/wdcancelremotecopy) 取消為止。在網路狀況不佳時，傳輸可能會非常緩慢地進行，而不是失敗。
* **失敗時會保留進度。** 失敗前已成功複製的檔案會保留在目的地上。當呼叫端重試複製時，差異複製行為可確保只傳輸未完成或遺失的檔案；先前已複製的檔案不會重新傳輸。
* **會回報磁碟空間錯誤。** 如果目的地裝置在複製期間磁碟空間不足，作業會失敗並傳回錯誤，而不是停止回應。
* **傳輸層級的復原能力。** 底層傳輸層會透明地處理低階封包重新傳輸。輕微的網路異常 (例如單一封包遺失) 不會導致作業失敗。不過，持續失去連線最終會導致錯誤。
* **建議的重試模式。** `WdRemoteCopy` 失敗之後，只需使用相同參數再次呼叫 `WdRemoteCopy` 即可。差異複製行為只會傳輸目的地上遺失或未完成的檔案，將重複工作降到最低。

## 取消

XBOX PC Remote Iteration API 為長時間執行的複製和刪除作業提供以控制代碼為基礎的取消模型。兩者都使用相同的 [WdCancellationHandle](/zh-TW/reference/remoting/structs/wdcancellationhandle) 類型。呼叫端負責控制代碼的生命週期：

1. 呼叫 [WdCreateCancellationHandle](/zh-TW/reference/remoting/functions/wdcreatecancellationhandle) 建立控制代碼。
2. 透過 `cancellationHandle` 參數將控制代碼傳遞給 [WdRemoteCopy](/zh-TW/reference/remoting/functions/wdremotecopy)。
3. 從另一個執行緒以該控制代碼呼叫 [WdCancelRemoteCopy](/zh-TW/reference/remoting/functions/wdcancelremotecopy)，以取消進行中的複製。`WdCancelRemoteCopy` 不會封鎖。發出取消訊號之後，`WdRemoteCopy` 可能會傳回 `S_OK` 或失敗。
4. `WdRemoteCopy` 傳回之後，呼叫 [WdCloseCancellationHandle](/zh-TW/reference/remoting/functions/wdclosecancellationhandle) 關閉控制代碼。

如果多個元件需要參考相同的取消控制代碼，請使用 [WdDuplicateCancellationHandle](/zh-TW/reference/remoting/functions/wdduplicatecancellationhandle) 複製它。每個複本都必須獨立關閉。

[WdDeleteRemoteFiles](/zh-TW/reference/remoting/functions/wddeleteremotefiles) 遵循相同的控制代碼型模型，使用 [WdCancelRemoteDelete](/zh-TW/reference/remoting/functions/wdcancelremotedelete) 發出取消訊號。觀察到取消時，會停止用戶端等待並傳回 `S_OK`，而不確認端點是否已完成。已在端點上開始的刪除會獨立繼續進行；取消不會還原已刪除的項目。

## 通用根目錄

通用根目錄是遠端裝置上預先設定的已知位置，遊戲通常會複製到這些位置或從這些位置啟動。呼叫端不需要指定完整的絕對路徑，而是可以使用 [WdCopyOptions](/zh-TW/reference/remoting/structs/wdcopyoptions) 或 [WdLaunchOptions](/zh-TW/reference/remoting/structs/wdlaunchoptions) 中的 `commonRootAlias` 欄位，以別名參考這些位置。

對於複製作業，`CopyTo` 的遠端路徑是 `destinationPath`，`CopyFrom` 的遠端路徑是 `sourcePath`。如果該路徑是絕對路徑，則會忽略 `commonRootAlias`。如果是相對路徑，則會依據別名所識別的通用根目錄進行解析。如果未指定別名，則會使用預設的通用根目錄位置。

## 錯誤碼

如需 API 特定錯誤碼的完整清單 (包括描述、根本原因和疑難排解指引)，請參閱 [XBOX PC Remote Iteration API 錯誤碼](/zh-TW/reference/remoting/error-codes)。

## 版本控制、服務與散發

如需 API NuGet、WinGet 和可執行檔的版本號碼，請參閱 [XBOX PC Remote Iteration 發行版本](/zh-TW/reference/remoting/release-versions)。

Remote Iteration Tools (RIT) API 遵循**語意化版本控制 2.0.0** (`MAJOR.MINOR.PATCH`)，為相容性、升級和長期支援提供明確的預期。所有公開的 RIT API 程式庫都透過 **NuGet** 散發，可使用標準的相依性管理和更新工作流程。

### 版本控制模型

下列相容性預期適用於非預覽版本。對於預覽套件，請在升級之前參閱 API 特定的變更歷程記錄，以了解宣告、配置和行為的變更。

#### 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` 版本。

### 升級預期

建議開發人員採用 `PATCH` 和 `MINOR` 更新，以在 `MAJOR` 版本內保持最新狀態。`MAJOR` 版本升級應明確規劃並驗證，以確保與生產工作流程的相容性。

### API 與 wdEndpoint 版本相容性

RIT API 用戶端程式庫與在遠端裝置上執行的 `wdEndpoint` 應一律保持在相容的版本。將較新的 API 版本與較舊的 `wdEndpoint` 搭配使用，可能會導致 `E_SERVERTOOOLD` 錯誤或非預期的行為。為了確保正確的行為、完整的回溯相容性，以及對最新 API 功能的支援，建議每當更新 API 用戶端程式庫時，都在所有遠端裝置上更新 `wdEndpoint`。如需 `wdEndpoint` 的最低版本需求，請參閱 NuGet 套件版本資訊。

## 需求

| 需求 | 值 |
| - | - |
| **標頭** | WdRemoteIteration.h |
| **程式庫** | wdremoteapi.lib |
| **NuGet 套件** | [Microsoft.GDK.RemoteIterationClientApi](https://aka.ms/GameDevRemoteAPI) |
| **支援的作業系統** | Windows 11 及更新版本 |
| **支援的架構** | x64, ARM64 |

## 概念文件

* [版本資訊 - XBOX PC Remote Tools (2026 年 3 月)](/zh-TW/tools/tools-pc/xbox-pc-remote-tools/release-notes/2603)

## 另請參閱

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


## Related topics

- [XBOX PC Remote Iteration API](/reference/remoting/remoteiteration_members.md)
- [API XBOX PC Remote Iteration](/es/reference/remoting/remoteiteration_members.md)