​

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 ciblant 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 rapides pendant le développement de jeux : les développeurs peuvent générer localement, puis déployer et tester sur du matériel distant sans gestion manuelle des fichiers.

​

Disponibilité de l’API

Cette référence décrit la dernière version de l’API. Sauf indication d’une version ultérieure, les déclarations publiques de l’API sont disponibles dans RIT 0.0.8-Preview, la première version publique de l’API. Introduit dans indique quand une déclaration a été ajoutée. Pris en charge à partir de indique quand 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 de la documentation. Les libellés de version utilisent la version WinGet. Le tableau des versions associe chaque libellé au package NuGet de l’API et aux versions de l’outil en ligne de commande.

​

Quand l’utiliser

• Déployer des builds de jeu depuis 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 lors des 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 depuis votre PC de développement.
• Automatiser des flux de travail de build, déploiement et 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 sur des appareils Windows distants, en local 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’une des extrémités doit être le PC local.
• N’utilisez pas cette API si l’appareil distant n’a pas été appairé 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 nécessitent les versions indiquées sur leurs pages de référence.
• Appairage des appareils : le PC local et l’appareil distant doivent être appairés et mutuellement approuvés en les provisionnant à l’aide de l’application XBOX PC Toolbox.
• 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 est une application WPF C# qui montre comment déployer, lancer, reprendre et arrêter des jeux sur un appareil distant, et annuler un déploiement en cours.

​

Fonctions

​

Structures

​

Énumérations

​

Rappels

​

Modèle de threading

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

• Une seule copie à la fois. Un seul appel à WdRemoteCopy peut être actif à un moment donné, quels que soient l’appareil cible ou le chemin de destination. Appeler WdRemoteCopy alors qu’une autre copie est déjà en cours entraîne un comportement non défini.
• Les autres fonctions peuvent être appelées sans risque pendant une copie. Des fonctions telles que WdLaunchRemoteGame, WdTerminateRemoteGame, WdResumeRemoteGame et WdRegisterRemoteXboxGame peuvent être appelées depuis des threads distincts pendant qu’une copie est en cours.
• Les opérations distantes sont bloquantes. Des fonctions telles que WdRemoteCopy et WdDeleteRemoteFiles bloquent en attendant le résultat de l’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 depuis un autre thread pour signaler l’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 toujours appeler WdTerminateRemoteGame une fois la connectivité rétablie.

​

Comportement des nouvelles tentatives

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 réseau ou d’une autre erreur temporaire, il incombe à 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 renvoie une erreur. L’appelant doit appeler à nouveau la fonction pour réessayer.
• Aucun délai d’expiration configurable. WdRemoteCopy n’impose pas de 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é via WdCancelRemoteCopy. Dans des conditions réseau 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 restent sur la destination. Lorsque l’appelant réessaie 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 retransférés.
• 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 rester bloquée.
• Résilience au niveau du transport. La couche de transport sous-jacente gère de manière transparente la retransmission des paquets de bas niveau. Les problèmes réseau mineurs (comme un seul paquet perdu) ne provoquent pas l’échec de l’opération. En revanche, une perte de connectivité prolongée finit par provoquer une erreur.
• Modèle de nouvelle tentative recommandé. Après un échec de WdRemoteCopy, il suffit d’appeler à 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 sur la destination.

​

Annulation

L’API XBOX PC Remote Iteration fournit un modèle d’annulation basé 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 via le paramètre cancellationHandle.
3. Depuis 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 renvoyer S_OK ou un échec.
4. Après le retour de WdRemoteCopy, fermez le handle en appelant WdCloseCancellationHandle.

Si plusieurs composants doivent référencer le même handle d’annulation, utilisez WdDuplicateCancellationHandle pour le dupliquer. Chaque copie doit être fermée indépendamment. WdDeleteRemoteFiles suit le même modèle basé sur des handles, en utilisant WdCancelRemoteDelete pour signaler l’annulation. Une annulation constatée met fin à l’attente côté client et renvoie 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 manière 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 à l’aide 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, avec leurs descriptions, leurs causes racines et des conseils de résolution des problèmes, consultez Codes d’erreur de l’API XBOX PC Remote Iteration.

​

Gestion des versions, maintenance et distribution

Pour connaître les numéros de version NuGet de l’API, 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 de fournir des attentes claires en matière de compatibilité, de mises à niveau et de support à long terme. Toutes les bibliothèques publiques de l’API RIT sont distribuées via 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 en matière 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 à chaque API concernant 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 d’API ni le comportement à l’exécution, et peuvent être appliquées directement sans risque. La mise à jour vers une version PATCH plus récente ne nécessite 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 API doivent être modifiées ou supprimées à l’avenir, elles sont clairement marquées comme dépréciées, ce qui laisse aux développeurs le temps de migrer. Les mises à jour des dépendances sont examinées pour garantir 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 conseils de migration clairs. 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 support

Une fois qu’une version MAJOR ou MINOR de l’API RIT est publiée, elle entre dans une période de maintenance active avec une fenêtre de support cible 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 prise en charge.

​

Attentes en matière de mise à niveau

Les développeurs sont encouragés à rester à 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 de garantir 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 exécuté sur l’appareil distant doivent toujours être maintenus à des versions compatibles. L’utilisation d’une version de l’API plus récente 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 dernières 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 la version minimale requise de wdEndpoint.

​

Configuration requise

​

Documentation conceptuelle

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

​

Voir aussi

• WdRemoteCopy
• WdCancelRemoteCopy
• WdCreateCancellationHandle
• WdLaunchRemoteGame
• WdRegisterRemoteXboxGame