​

API XBOX PC Remote Iteration

Fournit des fonctions permettant de copier et de supprimer des fichiers, ainsi que de lancer, reprendre et arrêter des jeux sur des appareils Windows distants.

​

Vue d’ensemble

L’API XBOX PC Remote Iteration permet des flux de travail de développement sur PC qui ciblent des appareils Windows distants. Elle fournit un ensemble de fonctions C permettant de transférer des fichiers de jeu entre un PC local et un appareil distant, ainsi que de lancer et de gérer des processus de jeu sur l’appareil distant. L’API est conçue pour des boucles d’itération serrées pendant le développement de jeux, ce qui permet aux développeurs de générer localement, puis de déployer et de tester sur du matériel distant sans gestion manuelle des fichiers.

​

Disponibilité de l’API

Cette référence décrit la plus récente API. Sauf indication d’une version ultérieure, les déclarations de l’API publique sont disponibles dans RIT 0.0.8-Preview, la première version publique de l’API. Introduit dans indique à quel moment une déclaration a été ajoutée. Pris en charge à partir de indique à quel moment une option déclarée est devenue fonctionnelle. L’introduction d’une déclaration n’implique pas que les rappels ou paramètres actuellement inutilisés sont implémentés. Les sections Historique des modifications décrivent les modifications apportées aux déclarations ou au comportement de l’API, et non les corrections apportées à la documentation. Les étiquettes de version utilisent la version WinGet. Le tableau des versions associe chaque étiquette au package NuGet de l’API et aux versions des outils en ligne de commande.

​

Quand l’utiliser

• Déployer des builds de jeu d’un PC local vers un appareil Windows distant pendant le développement.
• Copier des fichiers mis à jour (copie delta) vers un appareil distant afin de réduire les temps de transfert pendant les builds itératives.
• Supprimer les sorties de build obsolètes d’un appareil distant avant de déployer une nouvelle build.
• Lancer, suspendre, reprendre et arrêter des processus de jeu sur un appareil distant à partir de votre PC de développement.
• Automatiser les flux de travail de génération, de déploiement et de test dans des pipelines d’intégration continue ciblant des appareils Windows distants.
• Créer des outils de studio personnalisés, ou s’y intégrer, pour le déploiement vers des appareils Windows distants, localement ou dans des laboratoires de test.

​

Quand NE PAS l’utiliser

• N’utilisez pas cette API pour le déploiement commercial ou en production de jeux sur les consoles des utilisateurs finaux.
• N’utilisez pas cette API pour transférer des fichiers entre deux appareils distants; l’un des points de terminaison doit être le PC local.
• N’utilisez pas cette API si l’appareil distant n’a pas été jumelé et configuré pour le développement à distance.

​

Prérequis

• Package NuGet : Microsoft.GDK.RemoteIterationClientApi version 0.1.0-preview.26.3.6001 ou ultérieure pour l’API de base. Les API et options plus récentes requièrent les versions indiquées sur leurs pages de référence.
• Jumelage des appareils : Le PC local et l’appareil distant doivent être jumelés et mutuellement approuvés au moyen de l’application XBOX PC Toolbox, qui sert à les provisionner.
• wdEndpoint : wdEndpoint doit être installé et en cours d’exécution sur l’appareil distant. L’installation de XBOX PC Toolbox installe et configure wdEndpoint par défaut.
• En-tête et bibliothèque : Incluez WdRemoteIteration.h et effectuez l’édition de liens avec wdremoteapi.lib.

​

Exemple

L’exemple Remote Iteration Tools Sample est une application WPF en C# qui montre comment déployer, lancer, reprendre et arrêter des jeux sur un appareil distant, et comment annuler un déploiement en cours.

​

Fonctions

​

Structures

​

Énumérations

​

Rappels

​

Modèle de thread

L’API XBOX PC Remote Iteration est conçue pour des opérations de copie à thread unique. Les règles suivantes s’appliquent :

• Une seule copie à la fois. Un seul appel WdRemoteCopy peut être actif à un moment donné, quel que soit l’appareil cible ou le chemin de destination. Appeler WdRemoteCopy pendant qu’une autre copie est déjà en cours entraîne un comportement indéfini.
• Les autres fonctions peuvent être utilisées en toute sécurité pendant une copie. Des fonctions comme WdLaunchRemoteGame, WdTerminateRemoteGame, WdResumeRemoteGame et WdRegisterRemoteXboxGame peuvent être appelées à partir de threads distincts pendant qu’une copie est en cours.
• Les opérations distantes sont bloquantes. Des fonctions comme WdRemoteCopy et WdDeleteRemoteFiles bloquent en attendant un résultat d’opération, une erreur ou une annulation constatée. WdCancelRemoteCopy et WdCancelRemoteDelete ne sont pas bloquantes.
• L’annulation est thread-safe. WdCancelRemoteCopy et WdCancelRemoteDelete peuvent être appelées à partir d’un autre thread pour signaler une annulation.
• Aucun état de connexion entre les opérations distantes. Chaque appel d’opération distante établit sa propre connexion à l’appareil distant. Il n’y a pas de session persistante; par exemple, si la connexion est interrompue après la fin de WdLaunchRemoteGame, vous pouvez quand même appeler WdTerminateRemoteGame une fois la connectivité rétablie.

​

Comportement de nouvelle tentative

L’API XBOX PC Remote Iteration ne réessaie pas automatiquement les opérations ayant échoué au niveau de l’API. Si une opération échoue en raison d’une interruption du réseau ou d’une autre erreur temporaire, il revient à l’appelant de réessayer.

• Aucune nouvelle tentative automatique. Si une opération de copie échoue (par exemple, en raison d’une perte de connectivité réseau), WdRemoteCopy retourne une erreur. L’appelant doit appeler de nouveau la fonction pour réessayer.
• Aucun délai d’expiration configurable. WdRemoteCopy n’impose aucun délai d’expiration à l’opération de copie. Le transfert se poursuit jusqu’à ce qu’il soit terminé, qu’une erreur se produise ou qu’il soit annulé au moyen de WdCancelRemoteCopy. Lorsque les conditions réseau sont dégradées, les transferts peuvent se poursuivre très lentement plutôt qu’échouer.
• La progression est conservée en cas d’échec. Les fichiers copiés avec succès avant un échec demeurent à la destination. Lorsque l’appelant relance la copie, le comportement de copie delta garantit que seuls les fichiers incomplets ou manquants sont transférés; les fichiers déjà copiés ne sont pas transférés de nouveau.
• Les erreurs d’espace disque sont signalées. Si l’appareil de destination manque d’espace disque pendant une copie, l’opération échoue avec une erreur au lieu de se bloquer.
• Résilience au niveau du transport. La couche de transport sous-jacente gère de façon transparente la retransmission de paquets de bas niveau. Les problèmes réseau mineurs (comme un seul paquet perdu) n’entraînent pas l’échec de l’opération. Cependant, une perte de connectivité prolongée finira par entraîner une erreur.
• Modèle de nouvelle tentative recommandé. Après un échec de WdRemoteCopy, appelez simplement de nouveau WdRemoteCopy avec les mêmes paramètres. Le comportement de copie delta réduit le travail redondant en transférant uniquement les fichiers manquants ou incomplets à la destination.

​

Annulation

L’API XBOX PC Remote Iteration fournit un modèle d’annulation fondé sur des handles pour les opérations de copie et de suppression de longue durée. Le même type WdCancellationHandle est utilisé pour les deux. L’appelant est responsable du cycle de vie du handle :

1. Créez un handle en appelant WdCreateCancellationHandle.
2. Passez le handle à WdRemoteCopy au moyen du paramètre cancellationHandle.
3. À partir d’un thread distinct, appelez WdCancelRemoteCopy avec le handle pour annuler la copie en cours. WdCancelRemoteCopy n’est pas bloquante. Une fois l’annulation signalée, WdRemoteCopy peut retourner S_OK ou un échec.
4. Une fois que WdRemoteCopy a retourné, fermez le handle en appelant WdCloseCancellationHandle.

Si plusieurs composants doivent faire référence au même handle d’annulation, utilisez WdDuplicateCancellationHandle pour le dupliquer. Chaque copie doit être fermée de façon indépendante. WdDeleteRemoteFiles suit le même modèle fondé sur des handles, en utilisant WdCancelRemoteDelete pour signaler l’annulation. Une annulation constatée met fin à l’attente du client et retourne S_OK sans confirmer la fin de l’opération sur le point de terminaison. La suppression déjà commencée sur le point de terminaison se poursuit de façon indépendante; l’annulation ne restaure pas les éléments supprimés.

​

Racines communes

Les racines communes sont des emplacements connus préconfigurés sur l’appareil distant, vers lesquels les jeux sont généralement copiés ou à partir desquels ils sont lancés. Au lieu de spécifier un chemin absolu complet, les appelants peuvent faire référence à ces emplacements par alias au moyen du champ commonRootAlias de WdCopyOptions ou de WdLaunchOptions. Pour les opérations de copie, le chemin distant est destinationPath pour CopyTo et sourcePath pour CopyFrom. Si ce chemin est absolu, commonRootAlias est ignoré. S’il est relatif, il est résolu par rapport à la racine commune identifiée par l’alias. Si aucun alias n’est spécifié, l’emplacement de racine commune par défaut est utilisé.

​

Codes d’erreur

Pour obtenir la liste complète des codes d’erreur propres à l’API, y compris les descriptions, les causes premières et les conseils de dépannage, consultez Codes d’erreur de l’API XBOX PC Remote Iteration.

​

Gestion des versions, maintenance et distribution

Pour les numéros de version NuGet de l’API, de WinGet et des exécutables, consultez Versions de XBOX PC Remote Iteration. L’API Remote Iteration Tools (RIT) suit la gestion sémantique de version 2.0.0 (MAJOR.MINOR.PATCH) afin d’établir des attentes claires en matière de compatibilité, de mises à niveau et de soutien à long terme. Toutes les bibliothèques publiques de l’API RIT sont distribuées au moyen de NuGet, ce qui permet d’utiliser les flux de travail standard de gestion des dépendances et de mise à jour.

​

Modèle de gestion des versions

Les attentes de compatibilité ci-dessous s’appliquent aux versions qui ne sont pas des préversions. Pour les packages en préversion, consultez l’historique des modifications propre à l’API pour connaître les modifications de déclaration, de disposition et de comportement avant d’effectuer une mise à niveau.

​

Versions PATCH

Les mises à jour PATCH apportent des correctifs de bogues et des améliorations de fiabilité. Ces mises à jour ne modifient pas les contrats de l’API ni le comportement à l’exécution, et peuvent être appliquées directement en toute sécurité. La mise à jour vers une version PATCH plus récente ne requiert aucune modification du code.

​

Versions MINOR

Les mises à jour MINOR introduisent de nouvelles API ou font évoluer les fonctionnalités existantes de manière rétrocompatible. Lorsque des modifications ou des retraits d’API sont prévus, ces API sont clairement marquées comme dépréciées, ce qui donne aux développeurs le temps de migrer. Les mises à jour des dépendances sont examinées afin d’assurer la compatibilité au sein d’une même version MAJOR.

​

Versions MAJOR

Les mises à jour MAJOR représentent des changements cassants intentionnels. Ces versions peuvent nécessiter des modifications du code ou des mises à jour des dépendances et sont accompagnées de directives de migration claires. La mise à niveau vers une nouvelle version MAJOR est considérée comme une décision explicite et volontaire, alignée sur les cycles normaux de validation et de publication.

​

Modèle de maintenance et de soutien

Une fois qu’une version MAJOR ou MINOR de l’API RIT est publiée, elle entre dans une période de maintenance active dont la fenêtre de soutien cible est d’environ 18 mois. Pendant cette période :

• Des versions PATCH sont approuvées pour corriger des bogues et améliorer la fiabilité des versions prises en charge.
• À mesure que de nouvelles versions sont publiées et que des correctifs et des modifications mineures améliorent les versions existantes et corrigent des bogues, plusieurs versions MAJOR et MINOR peuvent être maintenues simultanément.
• Les versions PATCH ne prolongent pas la durée de maintenance d’une version MAJOR ou MINOR.
• Les nouvelles fonctionnalités sont introduites uniquement dans des versions MINOR ou MAJOR plus récentes et ne sont pas rétroportées.

Une fois la fenêtre de maintenance terminée, la version est retirée et les développeurs doivent migrer vers une version MAJOR ou MINOR plus récente et prise en charge.

​

Attentes en matière de mise à niveau

Les développeurs sont encouragés à demeurer à jour au sein d’une version MAJOR en adoptant les mises à jour PATCH et MINOR. Les mises à niveau de version MAJOR doivent être planifiées et validées explicitement afin d’assurer la compatibilité avec les flux de travail de production.

​

Compatibilité des versions de l’API et de wdEndpoint

La bibliothèque cliente de l’API RIT et le wdEndpoint qui s’exécute sur l’appareil distant doivent toujours être maintenus à des versions compatibles. L’utilisation d’une version plus récente de l’API avec un wdEndpoint plus ancien peut entraîner des erreurs E_SERVERTOOOLD ou un comportement inattendu. Pour garantir un comportement correct, une rétrocompatibilité complète et la prise en charge des plus récentes fonctionnalités de l’API, il est recommandé de mettre à jour wdEndpoint sur tous les appareils distants chaque fois que la bibliothèque cliente de l’API est mise à jour. Consultez les notes de publication du package NuGet pour connaître les exigences de version minimale de wdEndpoint.

​

Configuration requise

​

Documentation conceptuelle

• Notes de publication - XBOX PC Remote Tools (mars 2026)

​

Voir aussi

• WdRemoteCopy
• WdCancelRemoteCopy
• WdCreateCancellationHandle
• WdLaunchRemoteGame
• WdRegisterRemoteXboxGame