Cette page a été traduite par l'API Cloud Translation.

Débogueur

Déboguer votre projet avec Visual Studio Debugger (LLDB) lorsque vous utilisez l'extension Android Game Development

Exécuter le débogueur

Avant de pouvoir exécuter le débogueur, vous devez être en mesure de créer, de déployer et d'exécuter votre jeu sur Android. Pour en savoir plus, consultez la section Exécuter l'exemple.

Une fois que vous êtes sûr de pouvoir exécuter votre jeu sans le débogueur, vous pouvez utiliser celui-ci en appuyant sur F5 ou en sélectionnant Démarrer le débogage dans la section Déboguer. Une boîte de dialogue doit s'afficher lorsque le débogueur effectue son association avec le jeu.

Le lancement du débogueur peut prendre entre 10 secondes et une minute, voire plus, en fonction de la taille de votre application et du nombre de symboles à charger au démarrage. La première association à un nouvel appareil prend plus de temps, car le débogueur doit télécharger certaines bibliothèques Android de l'appareil vers la machine hôte. Si votre première tentative avec un nouvel appareil prend plus d'une minute, nous vous conseillons d'annuler la session de débogage, puis de la redémarrer.

Lorsque vous exécutez le débogueur de cette manière, le jeu démarre en mode Waiting for Debugger (En attente de Debugger) et n'exécute le code de votre jeu qu'une fois le débogueur connecté. Cela vous permet également de déboguer la section d'initialisation de votre jeu.

Pour en savoir plus sur des fonctionnalités spécifiques du débogueur Visual Studio, consultez la documentation de Visual Studio.

Association à un processus

Si vous souhaitez déboguer un jeu en cours d'exécution sur un appareil physique ou virtuel, vous pouvez associer le débogueur au processus à partir de Visual Studio.

Dans Visual Studio, assurez-vous qu'une solution Android est ouverte, puis effectuez les actions suivantes :

Accédez au menu Debug et sélectionnez Attach to process… (Associer au processus…).
Dans le menu déroulant Transport, sélectionnez Android Game Development Extension.
Dans le menu déroulant Qualifier (Qualificatif), sélectionnez votre appareil Android.
Sélectionnez le processus de jeu dans la liste des processus disponibles, puis cliquez sur Attach (Associer).

Associer au processus

Exécuter les commandes LLDB.Shell

Lorsqu'une session de débogage est active, utilisez la fenêtre de commande de Visual Studio pour exécuter les commandes LLDB.Shell.

Format de la commande :

LLDB.Shell [command]

Par exemple :

>LLDB.Shell expr myIntVariable = 9
Status:  Success
Output Message:
(int) $2 = 9

Visualisation des données

Spécificateurs de format

Vous pouvez modifier le format d'affichage d'une valeur dans les fenêtres Autos, Locals, Watch et DataTip variables à l'aide des spécificateurs de format.

Les indicateurs de format se trouvent à la fin des expressions. Ils commencent par une virgule suivie d'une chaîne courte. Par exemple, le spécificateur ,x de l'expression _myInt,x mettra en forme myInt en tant que valeur hexadécimale minuscule.

Vous pouvez utiliser des spécificateurs de format directement dans la fenêtre Watch ou dans les fenêtres Autos, Locals et DataTip en les ajoutant à vos expressions Natvis. Pour en savoir plus, consultez la page consacrée à Natvis.

Liste des spécificateurs de compatibilité

Nom du format	Spécificateur(s)	Description
booléen	Mrds	afficher cette valeur en tant que valeur booléenne vraie/fausse, à l'aide de la règle habituelle selon laquelle 0 correspond à "faux" et tout autre valeur à "vrai".
binaire	b	afficher ceci sous forme de séquence de bits
binaire, non précédée de "0b"	bb	afficher ceci sous forme d'une séquence de bits sans le préfixe 0b
octets	y	afficher les octets, mais essayez d'utiliser le format ASCII par exemple : (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._…
octets avec ASCII	Y	afficher les octets, mais essayez d'utiliser le format ASCII par exemple : (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._…
caractère	c	afficher les octets sous forme de caractères ASCII par exemple, (int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0
caractère imprimable	C	afficher les octets sous forme de caractères ASCII imprimables par exemple (int *) c.sp.x = P.._…
float complexe	F	interpréter cette valeur comme la partie réelle et imaginaire d'un nombre complexe à virgule flottante Exemple : (int *) c.sp.x = 2.76658e+19 + 4.59163e-41i
décimal	d, i	afficher cette valeur sous la forme d'un nombre entier signé (cela n'opère pas une conversion, mais affiche les octets sous forme d'un nombre entier avec un signe)
énumération	E, en	afficher cette valeur sous la forme d'une énumération, en affichant le nom de la valeur si elle est disponible ou la valeur entière dans le cas contraire par exemple, (enum enumType) val_type = eValue2
hexadécimal – minuscule	x, h	afficher ceci en minuscules au format hexadécimal (cette opération n'effectue pas de conversion, elle affiche simplement les octets au format hexadécimal)
hexadécimal – majuscule	X, H	afficher ceci en majuscules au format hexadécimal (cela n'opère pas une conversion, mais affiche simplement les octets au format hexadécimal)
hexadécimal – minuscule, séquence non précédée de 0x	xb, hb	afficher ceci en minuscules au format hexadécimal sans préfixe 0x (cela n'opère pas de conversion, mais affiche simplement les octets au format hexadécimal)
hexadécimal – majuscule, séquence non précédée de 0x au début	Xb, Hb	afficher ceci en majuscules au format hexadécimal sans préfixe 0x (cela n'opère pas de conversion, mais affiche simplement les octets en hexadécimal)
float	f	afficher cette valeur sous la forme d'un nombre à virgule flottante (cela n'effectue pas de conversion, mais interprète simplement les octets comme une valeur à virgule flottante IEEE754)
octal	o	afficher au format octal
type d'OS	O	afficher ceci en tant que MacOS OSType par exemple (float) x = '\n\x1f\xd7\n'
chaîne– chaîne C	s	afficher cette chaîne en tant que chaîne C terminée par 0 par exemple, "hello world"
string – chaîne C sans guillemets	sb	afficher cette chaîne sous forme de chaîne C se terminant par 0 sans guillemets, par exemple, hello world
chaîne – UTF-8	s8	afficher cette chaîne au format UTF-8 se terminant par 0 par exemple, u8"hello world ☕"
chaîne – UTF-8, sans guillemets	s8b	afficher cette chaîne au format UTF-8 se terminant par 0 sans guillemets par exemple, hello world ☕
chaîne – UTF-16	su	afficher cette chaîne sous la forme d'une chaîne UTF-16 se terminant par 0 Par exemple, u"hello world ☕"
chaîne – UTF-16, sans guillemets	sub	afficher cette chaîne sous la forme d'une chaîne UTF-16 se terminant par 0 sans guillemets Par exemple, hello world ☕"
chaîne – UTF-32	s32	afficher cette chaîne avec une chaîne UTF-32 se terminant par 00 par exemple, U"hello world ☕"
chaîne – UTF-32, sans guillemets	s32b	afficher cette chaîne avec une chaîne UTF-32 se terminant par 0 sans guillemets par exemple, hello world ☕
unicode16	U	afficher ceci sous forme de caractères UTF-16 par exemple, (float) x = 0xd70a 0x411f
unicode32	U32	affichez ceci sous forme de caractères UTF-32 par exemple, (float) x = 0x411fd70a
valeur décimale non signée	u	afficher cette valeur sous la forme d'un nombre entier non signé (ceci n'effectue pas de conversion, mais affiche simplement les octets sous forme d'entier non signé)
pointeur	p	afficher cette page en tant que pointeur natif (sauf s'il s'agit vraiment d'un pointeur, l'adresse obtenue sera probablement incorrecte)
entier complexe	I	interpréter cette valeur comme la partie réelle et imaginaire d'un nombre entier complexe par exemple, (int *) pointer = 1048960 + 1i
tableau de caractères	a	afficher comme tableau de caractères par exemple (char) *c.sp.z = {X}
Brut	!	format brut ignorant la personnalisation des vues de type de données

Natvis

Le framework Natvis vous permet de personnaliser la façon dont Visual Studio affiche les types natifs dans les fenêtres des variables du débogueur. Par exemple, vous pouvez personnaliser les affichages des fenêtres Watch, Locals et Data Tips à l'aide de Natvis.

La fonctionnalité Natvis est activée par défaut, mais vous pouvez la désactiver dans Visual Studio en définissant l'option Tools > Options > Android Game Development Extension > Natvis (Outils > Options > Extension Android Game Development > Natvis) sur Disabled (Désactivé).

Chargement des fichiers Natvis

Visual Studio charge les fichiers Natvis à partir des trois emplacements ci-dessous et les actualise à chaque fois que vous démarrez une session de débogage. Les fichiers doivent respecter le schéma Natvis 2017 de Visual Studio.

Les fichiers .natvis faisant partie d'un projet chargé ou d'un élément de solution de premier niveau.
Le répertoire spécifique à l'utilisateur (%USERPROFILE%\Documents\Visual Studio 2017\Visualizers)
Le répertoire du système (%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers)

Actualisation des fichiers Natvis

Actualisez les fichiers Natvis lors d'une session de débogage en évaluant .natvisreload dans la fenêtre Command ou Watch.

Exemple de fichier Natvis

Cet exemple de fichier Natvis inclut toutes les balises et tous les attributs actuellement compatibles.

<?xml version="1.0" encoding="utf-8"?>
<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">

  <Type Name="demo::Vector&lt;*&gt;">
    <AlternativeType Name="MySimilarVectorType&lt;*&gt;"/>

    <!-- Included to show the <SmartPointer> feature is supported. -->
    <SmartPointer Optional="true" Usage="Minimal">ptr</SmartPointer>

    <!-- Included to show the <DisplayString> feature is supported. -->
    <DisplayString Condition="_size == 0" Optional="true">()</DisplayString>
    <DisplayString Condition="_size == 1">(x={_items[0]})</DisplayString>
    <DisplayString Condition="_size == 2">(x={_items[0]}, y={_items[1]})</DisplayString>
    <DisplayString Condition="_size == 3">(x={_items[0]}, y={_items[1]}, z={_items[2]})</DisplayString>
    <DisplayString>[Size={_size,x}] (x={_items[0]}, y={_items[1]}, z={_items[2]}, ...)</DisplayString>

    <!-- Included to show the <StringView> feature is supported. -->
    <StringView Condition="true" Optional="true">_stringViewText</StringView>

    <Expand HideRawView="false">
      <!-- Included to show the <Item> feature is supported. -->
      <Item Name="X" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 1" Optional="true">_items[0]</Item>
      <Item Name="Y" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 2" Optional="true">_items[1]</Item>
      <Item Name="Z" Condition="_size &lt; 4 &amp;&amp; _size &gt;= 3" Optional="true">_items[2]</Item>

      <!-- Included to show the <ArrayItems> feature is supported. -->
      <ArrayItems Condition="_size >= 4" Optional="true">
        <Size Condition="true" Optional="true">_size</Size>
        <ValuePointer Condition="true">_items</ValuePointer>
      </ArrayItems>

      <!-- Included to show the <IndexListItems> feature is supported. -->
      <IndexListItems Condition="true" Optional="true">
        <Size Condition="true" Optional="true">_listSize</Size>
        <ValueNode Condition="true">_list[%i]</ValueNode>
      </IndexListItems>

      <!-- Included to show the <LinkedListItems> feature is supported. -->
      <LinkedListItems Condition="true" Optional="true">
        <Size Optional="true">_listSize</Size>
        <HeadPointer>_head</HeadPointer>
        <NextPointer>_next</NextPointer>
        <ValueNode>_value</ValueNode>
      </LinkedListItems>

      <!-- Included to show the <ExpandedItem> feature is supported. -->
      <ExpandedItem Condition="true" Optional="true">_childVar</ExpandedItem>

      <!-- Included to show the <Synthetic> feature is supported. -->
      <Synthetic Name="[Size]" Condition="true" Optional="true">
        <DisplayString>_size</DisplayString>
        <Expand HideRawView="true">
          <!-- Any supported <Expand> sub-tags. -->
        </Expand>
      </Synthetic>

      <!-- Included to show the <TreeItems> feature is supported. -->
      <TreeItems Condition="true" Optional="true">
        <Size>_treeSize</Size>
        <HeadPointer>_head</HeadPointer>
        <LeftPointer>_left</LeftPointer>
        <RightPointer>_right</RightPointer>
        <ValueNode>_value</ValueNode>
      </TreeItems>

      <!-- Included to show format specifiers are supported. -->
      <Item Name="[Hex Dump at {_index,x}]">myInt[_index],x</Item>
    </Expand>
  </Type>
</AutoVisualizer>

Créer des fichiers Natvis

Visual Studio permet de créer vos propres fichiers Natvis. Pour en savoir plus sur la personnalisation des fenêtres de variables du débogueur, accédez à MSDN.

Déboguer les fichiers Natvis

Dans certains cas, les erreurs sont présentées comme la valeur d'une variable (par exemple, dans les fenêtres Auto, Watch, etc.). Exemple : <error: use of undeclared identifier 'missingVar'>

Pour en savoir plus sur l'erreur, ouvrez le fichier GoogleAndroid.log à partir de la barre d'outils de l'extension Android Game Development.

Limites connues

Si votre balise ou votre attribut ne figure pas dans l'exemple de fichier ci-dessus, cela signifie qu'elle ou il n'est pas compatible pour le moment. Visual Studio ignore les attributs et les balises non compatibles. Vous pouvez donc les conserver dans un fichier Natvis existant. Celui-ci fonctionnera s'il utilise notre schéma.
L'attribut Usage, bien que requis par le schéma, n'est pas compatible avec <SmartPointer>. Toutefois, LLDB ne limite pas l'accès aux opérateurs définis en C++. Par conséquent, tout opérateur requis peut être défini à la place en C++.