XBOX PC Remote Iteration API
提供在遠端 Windows 型裝置上複製和刪除檔案，以及啟動、繼續和終止遊戲的函式。概觀
XBOX PC Remote Iteration API 可啟用以遠端 Windows 裝置為目標的 PC 型開發工作流程。它提供一組 C 函式，用於在本機 PC 與遠端裝置之間傳輸遊戲檔案，以及在遠端裝置上啟動和管理遊戲處理程序。此 API 專為遊戲開發期間的緊密反覆運算循環而設計，可讓開發人員在本機建置，並在遠端硬體上部署和測試，無需手動管理檔案。API 可用性
本參考說明最新的 API。除非另有指定較新的版本，否則公開 API 宣告自 RIT 0.0.8-Preview (初始公開 API 版本) 起提供。 推出版本表示宣告新增的時間。支援起始版本表示已宣告的選項開始運作的時間。宣告的推出並不代表目前未使用的回呼或設定已實作。變更歷程記錄章節描述 API 宣告或行為的變更，而非文件的更正。 版本標籤使用 WinGet 版本。發行版本表格會將每個標籤對應到 API NuGet 套件和命令列工具版本。使用時機
- 在開發期間將遊戲組建從本機 PC 部署到遠端 Windows 裝置。
- 將更新的檔案 (差異複製) 複製到遠端裝置，以在反覆建置期間將傳輸時間降到最低。
- 在部署新組建之前，從遠端裝置移除過時的組建輸出。
- 從開發 PC 在遠端裝置上啟動、暫停、繼續和終止遊戲處理程序。
- 在以遠端 Windows 裝置為目標的持續整合管線中，自動化建置-部署-測試工作流程。
- 建置或整合至自訂工作室工具，以在本機或測試實驗室中部署到遠端 Windows 裝置。
不應使用的時機
- 請勿使用此 API 將遊戲以零售或生產方式部署到終端使用者主機。
- 請勿使用此 API 在兩個遠端裝置之間傳輸檔案；其中一個端點必須是本機 PC。
- 如果遠端裝置尚未配對並設定為遠端開發，請勿使用此 API。
必要條件
- NuGet 套件： 基本 API 需要 Microsoft.GDK.RemoteIterationClientApi 0.1.0-preview.26.3.6001 版或更新版本。較新的 API 和選項需要其參考頁面上所標示的版本。
- 裝置配對： 本機 PC 與遠端裝置必須使用 XBOX PC Toolbox 應用程式佈建，以完成配對並相互信任。
- wdEndpoint：
wdEndpoint必須已安裝並在遠端裝置上執行。XBOX PC Toolbox 安裝程式預設會安裝並設定wdEndpoint。 - 標頭和程式庫： 包含
WdRemoteIteration.h並連結wdremoteapi.lib。
範例
Remote Iteration Tools Sample 是一個 C# WPF 應用程式，示範如何在遠端裝置上部署、啟動、繼續和終止遊戲，以及取消進行中的部署。函式
結構
列舉
回呼
執行緒模型
XBOX PC Remote Iteration API 是針對單一執行緒的複製作業所設計。適用下列規則：- 一次一個複製作業。 無論目標裝置或目的地路徑為何，任何時候都只能有一個 WdRemoteCopy 呼叫處於作用中狀態。在另一個複製作業進行中時呼叫
WdRemoteCopy，會導致未定義的行為。 - 複製期間可安全使用其他函式。 在複製進行中時，可以從其他執行緒呼叫 WdLaunchRemoteGame、WdTerminateRemoteGame、WdResumeRemoteGame 和 WdRegisterRemoteXboxGame 等函式。
- 遠端作業會封鎖。
WdRemoteCopy和WdDeleteRemoteFiles等函式會封鎖並等待作業結果、錯誤或觀察到的取消。WdCancelRemoteCopy和WdCancelRemoteDelete不會封鎖。 - 取消是執行緒安全的。 可以從另一個執行緒呼叫 WdCancelRemoteCopy 和 WdCancelRemoteDelete 來發出取消訊號。
- 遠端作業之間沒有連線狀態。 每個遠端作業呼叫都會建立自己與遠端裝置的連線。沒有持續性工作階段；例如，如果在 WdLaunchRemoteGame 完成之後連線中斷，在恢復連線後仍可呼叫 WdTerminateRemoteGame。
重試行為
XBOX PC Remote Iteration API 不會在 API 層級自動重試失敗的作業。如果作業因網路中斷或其他暫時性錯誤而失敗，由呼叫端負責重試。- 不會自動重試。 如果複製作業失敗 (例如因為失去網路連線)，
WdRemoteCopy會傳回錯誤。呼叫端必須重新叫用該函式以重試。 - 沒有可設定的逾時。
WdRemoteCopy不會對複製作業施加逾時。它會持續傳輸，直到完成、發生錯誤，或透過 WdCancelRemoteCopy 取消為止。在網路狀況不佳時，傳輸可能會非常緩慢地進行，而不是失敗。 - 失敗時會保留進度。 失敗前已成功複製的檔案會保留在目的地上。當呼叫端重試複製時，差異複製行為可確保只傳輸未完成或遺失的檔案；先前已複製的檔案不會重新傳輸。
- 會回報磁碟空間錯誤。 如果目的地裝置在複製期間磁碟空間不足，作業會失敗並傳回錯誤，而不是停止回應。
- 傳輸層級的復原能力。 底層傳輸層會透明地處理低階封包重新傳輸。輕微的網路異常 (例如單一封包遺失) 不會導致作業失敗。不過，持續失去連線最終會導致錯誤。
- 建議的重試模式。
WdRemoteCopy失敗之後，只需使用相同參數再次呼叫WdRemoteCopy即可。差異複製行為只會傳輸目的地上遺失或未完成的檔案，將重複工作降到最低。
取消
XBOX PC Remote Iteration API 為長時間執行的複製和刪除作業提供以控制代碼為基礎的取消模型。兩者都使用相同的 WdCancellationHandle 類型。呼叫端負責控制代碼的生命週期：- 呼叫 WdCreateCancellationHandle 建立控制代碼。
- 透過
cancellationHandle參數將控制代碼傳遞給 WdRemoteCopy。 - 從另一個執行緒以該控制代碼呼叫 WdCancelRemoteCopy，以取消進行中的複製。
WdCancelRemoteCopy不會封鎖。發出取消訊號之後，WdRemoteCopy可能會傳回S_OK或失敗。 WdRemoteCopy傳回之後，呼叫 WdCloseCancellationHandle 關閉控制代碼。
S_OK，而不確認端點是否已完成。已在端點上開始的刪除會獨立繼續進行；取消不會還原已刪除的項目。
通用根目錄
通用根目錄是遠端裝置上預先設定的已知位置，遊戲通常會複製到這些位置或從這些位置啟動。呼叫端不需要指定完整的絕對路徑，而是可以使用 WdCopyOptions 或 WdLaunchOptions 中的commonRootAlias 欄位，以別名參考這些位置。
對於複製作業，CopyTo 的遠端路徑是 destinationPath，CopyFrom 的遠端路徑是 sourcePath。如果該路徑是絕對路徑，則會忽略 commonRootAlias。如果是相對路徑，則會依據別名所識別的通用根目錄進行解析。如果未指定別名，則會使用預設的通用根目錄位置。
錯誤碼
如需 API 特定錯誤碼的完整清單 (包括描述、根本原因和疑難排解指引)，請參閱 XBOX PC Remote Iteration API 錯誤碼。版本控制、服務與散發
如需 API NuGet、WinGet 和可執行檔的版本號碼，請參閱 XBOX PC Remote Iteration 發行版本。 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 套件版本資訊。