Debugger

Wenn Sie die Android Game Development Extension verwenden, können Sie Fehler in Ihrem Projekt mit dem Visual Studio Debugger (LLDB) beheben.

Debugger ausführen

Damit Sie den Debugger ausführen können, müssen Sie Ihr Spiel auf Android erstellen, bereitstellen und ausführen können. Weitere Informationen finden Sie im Abschnitt Beispiel ausführen.

Wenn Sie sichergestellt haben, dass Sie Ihr Spiel ohne den Debugger ausführen können, können Sie ihn verwenden. Drücken Sie dazu F5 oder wählen Sie im Menü Fehlerbehebung den Eintrag Debugging starten aus. Ein Dialogfeld sollte angezeigt werden, während der Debugger an das Spiel angehängt wird.

Das Starten des Debuggers dauert je nach Größe Ihrer Anwendung und der Anzahl der Symbole, die beim Start geladen werden müssen, zwischen 10 Sekunden und einer Minute oder länger. Wenn das Gerät zum ersten Mal an ein neues Gerät angeschlossen wird, dauert es länger, da der Debugger einige Android-Bibliotheken vom Gerät auf den Hostcomputer herunterladen muss. Wenn Ihre ersten Versuche mit einem neuen Gerät länger als eine Minute dauern, sollten Sie die Fehlerbehebungssitzung abbrechen und dann neu starten.

Wenn Sie den Debugger auf diese Weise ausführen, wird das Spiel im Modus Warten auf den Debugger gestartet und der Code Ihres Spiels wird erst ausgeführt, wenn eine Verbindung zum Debugger hergestellt wird. Auf diese Weise können Sie auch den Initialisierungsbereich Ihres Spiels debuggen.

Weitere Informationen zu bestimmten Visual Studio-Debugger-Features finden Sie in der Visual Studio-Dokumentation.

Anhängen an einen Prozess

Wenn Sie Fehler in einem Spiel beheben möchten, das bereits auf einem physischen oder virtuellen Gerät ausgeführt wird, können Sie den Debugger über Visual Studio an den Prozess anhängen.

Prüfen Sie in Visual Studio, ob eine Android-Lösung geöffnet ist, und führen Sie folgende Schritte aus:

  1. Öffnen Sie das Menü Debug (Fehlerbehebung) und wählen Sie Attach to Process... (An Prozess anhängen) aus.
  2. Wählen Sie im Drop-down-Menü Transport die Option Android Game Development Extension aus.
  3. Wählen Sie im Drop-down-Menü Qualifier Ihr Android-Gerät aus.
  4. Wählen Sie den Spielprozess aus der Liste der verfügbaren Prozesse aus und klicken Sie auf Anhängen.

An Prozess anhängen

LLDB.Shell-Befehle ausführen

Verwenden Sie bei aktiver Debugging-Sitzung das Befehlsfenster von Visual Studio, um LLDB.Shell-Befehle auszuführen.

Befehlsformat:

LLDB.Shell [command]

Beispiel:

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

Datenvisualisierung

Formatspezifizierer

Sie können das Format, in dem ein Wert in den Fenstern Autos, Locals, Watch und DataTip angezeigt wird, mithilfe von Formatspezifizierern ändern.

Formatspezifizierer befinden sich am Ende von Ausdrücken. Sie beginnen mit einem Komma, gefolgt von einer kurzen Zeichenfolge. Der Spezifizierer ,x im Ausdruck _myInt,x formatiert beispielsweise myInt als Hexadezimalwert in Kleinbuchstaben.

Formatspezifizierer können direkt im Fenster Watch oder in den Fenstern Autos, Locals und DataTip verwendet werden, indem sie Ihren Natvis-Ausdrücken hinzugefügt werden. Weitere Informationen finden Sie unter Natvis.

Liste der Supportspezifizierer

Formatname Spezifizierer Beschreibung
boolean Mrd. Dies als boolescher Wert "wahr" oder "falsch" anzeigen, wobei die übliche Regel gilt, dass 0 falsch und alles andere wahr ist
Binärprogramm b Dies als Folge von Bits anzeigen
binär, keine führende 0b bb Dies als eine Sequenz von Bits ohne das Präfix 0b anzeigen
Bytes y Bytes anzeigen, aber auch als ASCII-Zeichen darstellen
z.B. (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
Byte mit ASCII Y Bytes anzeigen, aber auch als ASCII-Zeichen darstellen
z.B. (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
Zeichen c Byte als ASCII-Zeichen anzeigen
z.B. (int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0
druckbares Zeichen C Bytes anzeigen als druckbare ASCII-Zeichen
z. B. (int *) c.sp.x = P.._......
Komplexe Gleitkommazahl F Interpretiere diesen Wert als reeller und imaginärer Teil einer komplexen Gleitkommazahl
z. B. (int *) c.sp.x = 2,76658e+19 + 4,59163e-41i
Aufzählungszeichen Dezimalzahlen T, I dies als vorzeichenbehaftete Ganzzahl anzeigen (es wird kein Umwandeln durchgeführt, sondern die Bytes werden einfach als Ganzzahl mit Vorzeichen angezeigt)
Aufzählung E,de dies als Aufzählung anzeigen und den Namen des Werts ausgeben, sofern verfügbar, oder ansonsten den Ganzzahlwert
z.B. (enum enumType) val_type = eValue2
hexadezimal – Kleinbuchstabe X, H Dies wird in Hexadezimalschreibweise in Kleinbuchstaben angezeigt. (Dies führt keine Umwandlung durch, sondern zeigt die Byte einfach als Hexadezimalwert an.)
hexadezimal (Großbuchstaben) X, H Dies wird in Hexadezimalschreibweise in Großbuchstaben angezeigt. Damit wird keine Umwandlung durchgeführt, sondern die Bytes werden einfach als Hexadezimalwert angezeigt.
Hexadezimal – Kleinbuchstabe, kein vorangestelltes 0x XB, HB Dies wird in Kleinschreibung in Hexadezimalschreibweise ohne 0x-Präfix angezeigt (dadurch wird keine Umwandlung durchgeführt, sondern die Bytes werden einfach als Hexadezimalwert angezeigt)
hexadezimal – Großbuchstaben, keine vorangestellte 0x Xb, Hb Dies wird in Hexadezimalschreibweise in Großbuchstaben ohne 0x-Präfix angezeigt (dadurch wird keine Umwandlung durchgeführt, sondern die Bytes werden einfach als Hexadezimalwert angezeigt).
schweben f dies als Gleitkommazahl (hier wird keine Umwandlung durchgeführt, sondern die Byte werden einfach als IEEE754-Gleitkommawert interpretiert)
Oktal o Dies in Oktalschreibweise anzeigen
Betriebssystemtyp O Anzeige als macOS OSType
z.B. (Gleitkommazahl) x = '\n\x1f\xd7\n'
Zeichenfolge - C-String s Dies als 0-terminierten C-String anzeigen
z.B. „Hello World“
string - C-String, keine Anführungszeichen SB Dies als 0-terminierten C-String ohne Anführungszeichen anzeigen,
z.B. „hello world“
String – UTF-8 S8 dies als UTF-8-terminierter UTF-8-String anzeigen
z.B. u8„Hallo Welt ☕“
String: UTF-8, keine Anführungszeichen S8b Dies als einen UTF-8-terminierten UTF-8-String ohne Anführungszeichen anzeigen
z.B. „hello world“ ☕
String – UTF-16 su dies als einen UTF-16-terminierten UTF-16-String anzeigen
z.B. „Hallo Welt ☕“
String: UTF-16, keine Anführungszeichen sub Dies als UTF-16-terminierter UTF-16-String ohne Anführungszeichen anzeigen
z.B. hello world ☕
String – UTF-32 S32 Dies wird als UTF-32-String mit 0 Beendet angezeigt,
z. B. „Hallo Welt ☕“.
String: UTF-32, keine Anführungszeichen S32B Dies als 0-terminierten UTF-32-String ohne Anführungszeichen anzeigen
z.B. hello world ☕
Unicode 16 U dies als UTF-16-Zeichen anzeigen
z.B. (Gleitkommazahl) x = 0xd70a 0x411f
Unicode 32 U32 dies als UTF-32-Zeichen anzeigen
z.B. (Gleitkommazahl) x = 0x411fd70a
Dezimalzahl ohne Vorzeichen u wird als vorzeichenlose Ganzzahl angezeigt (es wird keine Umwandlung durchgeführt, sondern die Byte werden nur als vorzeichenlose Ganzzahl angezeigt)
Zeiger p die dies als nativen Zeiger anzeigen (es sei denn, es handelt sich um einen Zeiger, ist die resultierende Adresse wahrscheinlich ungültig)
komplexe Ganzzahl I Interpretiere diesen Wert als reeller und imaginärer Teil einer komplexen Ganzzahl
z.B. Zeiger (int *) = 1048960 + 1i
Zeichenarray a Als Array mit Zeichen anzeigen
z.B. (char) *c.sp.z = {X}
Raw ! Rohformat, wobei die Anpassungen von Ansichten des Datentyps ignoriert werden.

Logo: Natvis

Mit dem Natvis-Framework können Sie anpassen, wie Visual Studio native Typen in den Debugger-Variablenfenstern anzeigt. Beispielsweise können Sie mit Natvis die Ansichten für die Fenster Watch (Uhr), Locals (Lokales) und Data Tips (Datentipps) anpassen.

Die Natvis-Funktion ist standardmäßig aktiviert, kann aber in Visual Studio deaktiviert werden. Dazu setzen Sie das Flag Tools > Optionen > Android Game Development Extension > Natvis auf Disabled.

Natvis-Dateien laden

Visual Studio lädt Natvis-Dateien aus den drei unten aufgeführten Speicherorten und aktualisiert sie jedes Mal, wenn Sie eine Debugging-Sitzung starten. Die Dateien müssen dem Natvis-Schema von Visual Studio 2017 entsprechen.

  • .natvis-Dateien, die Teil eines geladenen Projekts oder Lösungselements der obersten Ebene sind.
  • Das nutzerspezifische Verzeichnis (%USERPROFILE%\Documents\Visual Studio 2017\Visualizers)
  • Das systemweite Verzeichnis (%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers)
Natvis-Dateien aktualisieren

Aktualisieren Sie Natvis-Dateien während einer Fehlerbehebungssitzung, indem Sie .natvisreload im Befehls- oder Überwachungsfenster auswerten.

Natvis-Beispieldatei

Diese Natvis-Beispieldatei enthält alle derzeit unterstützten Tags und Attribute.

<?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>

Natvis-Dateien erstellen

Visual Studio unterstützt das Erstellen eigener Natvis-Dateien. Weitere Informationen zum Anpassen der Fenster für Debugger-Variablen finden Sie unter MSDN.

Debugging von Natvis-Dateien

In einigen Fällen werden Fehler als Value (Wert) einer Variablen dargestellt (z.B. in den Fenstern Auto, Watch usw.). Beispiel: <error: use of undeclared identifier 'missingVar'>

Weitere Details zum Fehler finden Sie, wenn Sie die Datei GoogleAndroid.log in der Symbolleiste der Android Game Development Extension öffnen.

Bekannte Einschränkungen

  • Wenn Ihr Tag oder Attribut in der Beispieldatei oben nicht aufgeführt ist, wird es derzeit nicht unterstützt. In Visual Studio werden nicht unterstützte Tags und Attribute ignoriert. Sie können sie also in einer vorhandenen Natvis-Datei belassen. Die Datei funktioniert, solange unser Schema verwendet wird.

  • Das Attribut Usage wird für <SmartPointer> nicht unterstützt, auch wenn es für das Schema erforderlich ist. LLDB beschränkt den Zugriff jedoch nicht auf in C++ definierte Operatoren, sodass alle erforderlichen Operatoren stattdessen in C++ definiert werden können.