XBOX PC Remote Iteration API
リモートの Windows ベース デバイスに対して、ファイルのコピー、ゲームの起動、再開、および終了を行う関数を提供します。アプリ ベースのワークフローをお探しですか？ XBOX PC Toolbox アプリ、
wdRemote と wdEndpoint のコマンドライン ツール、および Visual Studio リモート デバッガーについては、XBOX PC Remote Tools のチュートリアルを参照してください。はじめに
XBOX PC Remote Tools の概要
リモート Windows デバイスでのプロビジョニング、デプロイ、起動、デバッグ、イテレーションを行います。
クイックスタート
XBOX PC Toolbox アプリをインストールして、開発デバイスとターゲット デバイスをペアリングします。
wdRemote コマンドライン ツール
リモート イテレーション ワークフローをコマンドラインで制御します。
FAQ とトラブルシューティング
よくある質問、既知の問題、および修正方法。
概要
XBOX PC Remote Iteration API は、リモートの Windows デバイスを対象とする PC ベースの開発ワークフローを可能にします。ローカル PC とリモート デバイス間でのゲーム ファイル転送、リモート デバイス上でのゲーム プロセスの起動と管理、およびリモート実行のためのゲーム登録を行う C 関数のセットを提供します。この API は、ゲーム開発中の緊密なイテレーション ループのために設計されており、開発者はローカルでビルドし、手動でファイル管理を行うことなくリモート ハードウェアでデプロイおよびテストできます。使用する場面
- 開発中に、ローカル PC からリモート Windows デバイスへゲーム ビルドをデプロイする場合。
- イテレーティブ ビルド中の転送時間を最小化するために、更新されたファイル (差分コピー) をリモート デバイスにコピーする場合。
- 開発 PC からリモート デバイス上のゲーム プロセスを起動、中断、再開、終了する場合。
- リモート Windows デバイスを対象とした継続的インテグレーション パイプラインでビルド、デプロイ、テストのワークフローを自動化する場合。
- リモート Windows デバイスへのローカルまたはテスト ラボでのデプロイを行うカスタム スタジオ ツールを構築または統合する場合。
使用すべきでない場面
- この API は、リテール ゲームやエンドユーザー コンソールへの本番デプロイには使用しないでください。
- この API は、2 台のリモート デバイス間のファイル転送には使用しないでください。エンドポイントの一方はローカル PC である必要があります。
- リモート デバイスがペアリングされておらず、リモート開発用に構成されていない場合は、この API を使用しないでください。
前提条件
- NuGet パッケージ: Microsoft.GDK.RemoteIterationClientApi バージョン 0.1.0-preview.26.3.6001 以降。
- デバイスのペアリング: XBOX PC Toolbox アプリを使用してプロビジョニングし、ローカル PC とリモート デバイスをペアリングして相互に信頼させる必要があります。
- wdEndpoint: リモート デバイスに
wdEndpointがインストールされ、実行されている必要があります。XBOX PC Toolbox のセットアップでは、既定でwdEndpointがインストールおよび構成されます。 - ヘッダーとライブラリ:
WdRemoteIteration.hをインクルードし、wdremoteapi.libをリンクします。
関数
構造体
列挙型
コールバック
スレッド モデル
XBOX PC Remote Iteration API は、シングルスレッドのコピー操作向けに設計されています。次の規則が適用されます。- 同時に 1 つのコピーのみ。 ターゲット デバイスやコピー先のパスに関係なく、任意の時点でアクティブにできる WdRemoteCopy の呼び出しは 1 つだけです。別のコピーがすでに進行中に
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 は、互換性、アップグレード、および長期サポートに関する明確な期待を提供するために、セマンティック バージョニング 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 リリースに移行することが期待されます。
アップグレードの期待
開発者には、PATCH および MINOR 更新を取り入れることで、MAJOR バージョン内で最新の状態を保つことが推奨されます。MAJOR バージョンのアップグレードは、本番ワークフローとの互換性を確保するために、明示的に計画および検証する必要があります。
API と wdEndpoint のバージョン互換性
RIT API クライアント ライブラリと、リモート デバイス上で動作するwdEndpoint は、常に互換性のあるバージョンに保つ必要があります。より新しい API バージョンをより古い wdEndpoint と一緒に使用すると、E_SERVERTOOOLD エラーや予期しない動作が発生する可能性があります。正しい動作、完全な後方互換性、および最新の API 機能のサポートを保証するために、API クライアント ライブラリを更新するたびに、すべてのリモート デバイス上の wdEndpoint を更新することをお勧めします。最小限の wdEndpoint バージョン要件については、NuGet パッケージのリリース ノートを参照してください。
要件
概念ドキュメント
XBOX PC Remote Tools
リモート Windows デバイスをセットアップし、XBOX PC Remote Tools を使用してデプロイ、起動、デバッグ、イテレーションを行います。