Déboguer des projets XBOX à l'aide de Visual Studio

Le débogage des projets XBOX du Microsoft Game Development Kit (GDK) depuis Visual Studio est assuré par le composant XBOX Debugger, installé avec le Microsoft Game Development Kit (GDK). Visual Studio 2019 et 2022 sont pris en charge. XBOX Debugger est le débogueur par défaut de tous les projets dont la plateforme est Gaming.Xbox.One.x64 ou Gaming.Xbox.Scarlett.x64, comme illustré dans la capture d’écran suivante.

​

Configurer le débogueur de Visual Studio

Lorsque le débogueur est lancé avec F5 depuis Visual Studio, la console par défaut que vous avez définie à l’aide d’autres outils du Microsoft Game Development Kit (GDK), comme XBOX Manager ou xbConnect, est utilisée par défaut. Pour modifier ce comportement, spécifiez une console à l’aide de la propriété Remote IP Address de la section XBOX One de la page de propriétés du projet, comme illustré dans la capture d’écran suivante. La barre d’outils de débogage de Visual Studio comprend une liste déroulante qui indique la console sur laquelle le titre sera déployé lors d’un lancement par F5 ou Ctrl-F5. Cette liste déroulante comporte un bouton permettant d’accéder rapidement à la page de propriétés du projet s’il faut changer de console cible. Le débogueur peut aussi être lancé depuis l’XBOX Gaming Explorer. Dans ce cas, la console utilisée est celle identifiée dans le ruban de connexion en haut de l’XBOX Gaming Explorer, comme illustré dans la capture d’écran suivante.

​

Chemins des symboles

Les fichiers Program Database (.pdb) de plusieurs composants du Game OS peuvent être utilisés lors du débogage avec Visual Studio. Configurer Visual Studio pour qu’il utilise ces symboles permet par exemple d’obtenir des piles d’appels plus complètes lors d’un arrêt dans le débogueur. Certains symboles du Game OS sont installés sur votre PC de développement par le programme d’installation du Microsoft Game Development Kit (GDK), tandis que d’autres sont disponibles sur les serveurs de symboles publics de Microsoft. Les symboles du Game OS installés par le programme d’installation se trouvent sur le PC de développement dans C:\Program Files (x86)\Microsoft GDK<edition number>\GXDK\gameKit\symbols. Les .pdb indépendants de la plateforme se trouvent à la racine du dossier des symboles. Les .pdb propres à une plateforme se trouvent dans les sous-répertoires Xbox Series X|S et XboxOne. Pour ajouter le chemin du répertoire des symboles du Game OS sur votre PC local, utilisez le paramètre Symbols de la section Debugging de la boîte de dialogue Options de Visual Studio, comme illustré dans la capture d’écran suivante. Pour accéder aux symboles du Game OS disponibles sur le serveur de symboles public de Microsoft, cochez la case Microsoft Symbol Servers dans la boîte de dialogue Symbols. L’ajout des serveurs de symboles Microsoft comme emplacement de fichiers de symboles amène Visual Studio à rechercher sur le serveur de symboles tous les binaires chargés par votre titre. Une recherche exhaustive de symboles peut prendre du temps. Vous pouvez réduire ce temps de recherche en configurant Visual Studio pour qu’il ne recherche les .pdb que pour un ensemble précis de binaires utilisés par votre titre. Pour spécifier l’ensemble des binaires pour lesquels Visual Studio doit rechercher les .pdb, utilisez l’option Load only specified modules de la boîte de dialogue Options. La capture d’écran suivante montre Visual Studio configuré pour charger les symboles depuis le serveur de symboles public pour seulement quelques binaires sélectionnés.

​

Propriétés liées au débogage

Le débogueur peut être configuré plus avant au moyen d’un ensemble de propriétés exposées dans la boîte de dialogue des propriétés du projet et dans l’onglet Settings de l’XBOX Gaming Explorer. Ces propriétés permettent par exemple de passer des arguments de ligne de commande à votre titre et d’activer la journalisation du chargement des modules. Pour plus de renseignements sur les propriétés disponibles, consultez Propriétés de Visual Studio pour le développement XBOX et XBOX Gaming Explorer.

​

Attacher le débogueur à un titre en cours d’exécution

Le menu XBOX et l’XBOX Gaming Explorer comprennent des options de menu permettant d’attacher le débogueur à un jeu en cours d’exécution sur une console. Pour attacher le débogueur au jeu en cours d’exécution sur votre console par défaut, utilisez Attach to Running Game dans le menu XBOX. Le menu XBOX est accessible depuis la barre de menus de Visual Studio, comme illustré dans la capture d’écran suivante. Vous pouvez aussi attacher le débogueur à un jeu en cours d’exécution sur n’importe quelle console ajoutée avec l’XBOX Gaming Explorer. Les menus contextuels des sections Game Processes et Titles de l’onglet Home comprennent des éléments de menu permettant de s’attacher à un jeu en cours d’exécution, comme illustré dans la capture d’écran suivante. Le menu contextuel d’une console donnée dans l’onglet Consoles permet de s’attacher au jeu en cours d’exécution sur cette console, comme illustré dans la capture d’écran suivante. La boîte de dialogue Attach du menu Debug de Visual Studio permet aussi de s’attacher à un titre en cours d’exécution. Avec Visual Studio 2022, sélectionnez XBOX Direct Connection dans la liste déroulante Connection Type et saisissez l’adresse IP de l’hôte ou l’adresse IP du système de la console dans la zone de texte Connection Target. Les adresses IP de l’hôte et du système peuvent être déterminées à l’aide de l’outil en ligne de commande xbconnect. Avec Visual Studio 2019, sélectionnez Remote No Authentication dans la liste déroulante Connection Type et saisissez l’adresse IP de l’hôte de la console dans la zone de texte Connection Target.

​

Déboguer des projets XBOX avec Visual Studio 2022

Le débogage avec Visual Studio 2022 nécessite que le titre débogué soit généré avec le Microsoft Game Development Kit (GDK) d’octobre 2021 ou une version ultérieure. Cette dépendance s’explique par le fait que le Game OS fourni avec ces versions du Microsoft Game Development Kit (GDK) contient des binaires nécessaires au débogage avec Visual Studio 2022. L’erreur suivante s’affiche si vous tentez de déboguer avec Visual Studio 2022 sur un Game OS plus ancien.

​

Déboguer des builds empaquetés

Les options du menu contextuel de l’XBOX Gaming Explorer permettant de lancer un titre sous le débogueur ou de s’attacher à un titre en cours d’exécution fonctionnent aussi bien pour les builds empaquetés que pour les déploiements de fichiers non empaquetés. Les packages d’installation en streaming sont identifiés par le type de déploiement Install et l’icône correspondante dans l’XBOX Gaming Explorer, comme illustré dans la capture d’écran suivante.

​

Déboguer les transitions entre les états du cycle de vie du jeu

Pour prendre correctement en charge le cycle de vie du jeu, vous devez écrire des gestionnaires d’événements pour les transitions entre les états de cycle de vie complet, suspendu et contraint. Visual Studio fournit plusieurs fonctionnalités pour vous aider à écrire les gestionnaires d’événements robustes dont votre titre a besoin pour franchir correctement les transitions d’état du cycle de vie du jeu. Les menus contextuels de l’XBOX Gaming Explorer comprennent des options Suspend, Resume et Constrain pour votre titre, afin que vous puissiez déboguer vos gestionnaires sur un kit de développement. Notez que vous pouvez aussi déclencher manuellement ces transitions d’état depuis XBOX Manager et l’outil en ligne de commande xbApp. Quelle que soit la façon dont une transition d’état est déclenchée, des messages de diagnostic décrivant la transition, ainsi que les éventuels échecs, sont visibles dans xbWatson et dans la fenêtre XBOX System Monitor de Visual Studio. Dans un environnement commercial, les gestionnaires de l’événement Suspend doivent se terminer en moins d’une seconde, faute de quoi le système met fin à votre titre. Cette limite de temps de suspension ne doit évidemment pas toujours être appliquée sur les kits de développement, sans quoi le débogage d’un gestionnaire Suspend serait quasiment impossible. Par défaut, lorsque le débogueur de Visual Studio (ou tout autre débogueur en mode utilisateur) est attaché, le délai d’expiration de suspension d’une seconde est désactivé, ce qui vous laisse le temps nécessaire pour mener à bien votre tâche de débogage. Le débogueur de Visual Studio peut aussi être configuré pour réactiver le délai d’expiration de suspension lorsqu’il est attaché. Dans ce mode, si votre gestionnaire Suspend ne se termine pas dans la limite d’une seconde, le débogueur force un arrêt afin que vous puissiez voir où vous en étiez dans votre gestionnaire Suspend lorsque la limite de temps a expiré. L’exécution du débogueur dans ce mode permet de se faire une idée de la fréquence à laquelle votre gestionnaire Suspend dépasse la limite de temps, et pourquoi. Définissez la propriété Break On Suspend Timeout dans Visual Studio pour placer le débogueur dans un mode où le délai d’expiration de suspension est activé. L’arrêt du débogueur qui se produit dans ce mode a lieu sur un nouveau thread que le débogueur injecte dans le processus. Accédez au thread qui contient le gestionnaire Suspend pour commencer le débogage. Si aucun débogueur n’est attaché à votre titre lorsqu’un délai d’expiration de suspension survient, le système crée un vidage sur incident de mise en veille. Ces vidages sont accessibles à l’aide du panneau Memory Dump de xbWatson.

​

Débogage dynamique C++ dans Visual Studio 2022

Le débogage dynamique C++ est une nouvelle fonctionnalité de débogage qui offre une expérience de débogage complète pour le code optimisé sans compromettre les performances. Placez des points d’arrêt désoptimisés et effectuez un pas à pas détaillé n’importe où grâce à la désoptimisation des fonctions à la demande. Pour activer le débogage dynamique C++ : cliquez avec le bouton droit sur votre projet, Properties > Configuration Properties > Advanced > Advanced Properties > Use C++ Dynamic Debugging (preview). La version 17.14 Preview 2 ou ultérieure de Visual Studio 2022 est requise pour utiliser la fonctionnalité de débogage dynamique. Consultez https://aka.ms/dynamicdebugging pour en savoir plus.

​

Voir aussi

XBOX Gaming Explorer Visual Studio