Debugger

Esegui il debug del tuo progetto con Visual Studio Debugger (LLDB) quando utilizzi l'estensione Android Game Development.

Eseguire il debugger

Prima di poter eseguire il debugger, devi essere in grado di creare, implementare ed eseguire il tuo gioco su Android. Per maggiori dettagli, consulta la sezione Eseguire l'esempio.

Dopo aver verificato di poter eseguire il gioco senza il debugger, puoi utilizzare il debugger premendo F5 o selezionando la voce Avvia debug dal menu Debug. Dovresti visualizzare una finestra di dialogo mentre il debugger è in fase di collegamento al gioco.

L'avvio del debugger richiede da 10 secondi a 1 minuto o più, a seconda delle dimensioni dell'applicazione e della quantità di simboli che devono essere caricati all'avvio. La prima connessione a un nuovo dispositivo richiede più tempo, in quanto il debugger deve scaricare alcune librerie Android dal dispositivo alla macchina host. Se i primi tentativi con un nuovo dispositivo richiedono più di 1 minuto, è consigliabile annullare la sessione di debug e riavviarla.

Quando esegui il debugger in questo modo, il gioco viene avviato in modalità In attesa del debugger e non esegue il codice del gioco finché non si connette al debugger. In questo modo puoi anche eseguire il debug della sezione di inizializzazione del tuo gioco.

Puoi trovare ulteriori informazioni sulle funzionalità specifiche del debugger di Visual Studio consultando la documentazione di Visual Studio.

Collegamento a un processo

Se vuoi eseguire il debug di un gioco già in esecuzione su un dispositivo fisico o virtuale, puoi collegare il debugger al processo da Visual Studio.

In Visual Studio, assicurati che una soluzione Android sia aperta e:

  1. Vai al menu Debug e seleziona Allega al processo....
  2. Dal menu a discesa Trasporto, seleziona Android Game Development Extension (Estensione per lo sviluppo dei giochi Android).
  3. Dal menu a discesa Qualificatore, seleziona il tuo dispositivo Android.
  4. Seleziona il processo di gioco dall'elenco dei processi disponibili e fai clic su Allega.

Allega al processo

Esecuzione dei comandi LLDB.Shell in corso...

Con una sessione di debug attiva, utilizza la finestra dei comandi di Visual Studio per eseguire i comandi LLDB.Shell.

Formato comando:

LLDB.Shell [command]

Esempio:

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

Visualizzazione dei dati

Indicatori di formato

Puoi modificare il formato di visualizzazione di un valore nelle finestre Auto, Locali, Watch e variabili DataTip utilizzando gli identificatori di formato.

Gli identificatori di formato si trovano alla fine delle espressioni. Iniziano con una virgola seguita da una stringa corta. Ad esempio, l'identificatore ,x nell'espressione _myInt,x formatterà myInt come esadecimale minuscolo.

Gli identificatori di formato possono essere utilizzati direttamente nella finestra Watch o nelle finestre Auto, Locals e DataTip aggiungendoli alle espressioni Natvis. Per ulteriori informazioni, visita Natvis.

Elenco degli specificatiri di assistenza

Nome formato Identificatore/i Descrizione
boolean B mostra questo come un valore booleano vero/falso, utilizzando la regola consueta secondo cui 0 è falso e tutto il resto è vero
programma binario | file binario b mostralo come una sequenza di bit
binario, nessun 0b iniziale bb mostralo come una sequenza di bit senza prefisso 0b
byte y mostra i byte, ma prova a visualizzarli anche come caratteri ASCII
ad es. (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
byte con ASCII Y mostra i byte, ma prova a visualizzarli anche come caratteri ASCII
ad es. (int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....
carattere c mostra i byte come caratteri ASCII
ad es. (int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0
carattere stampabile C mostra i byte come caratteri ASCII stampabili
ad es. (int *) c.sp.x = P.._....
numero in virgola mobile complesso F interpreta questo valore come la parte reale e immaginaria di un numero complesso in virgola mobile
ad es. (int *) c.sp.x = 2,76658e+19 + 4,59163e-41i
decimale d, i mostra questo come un numero intero firmato (questa operazione non esegue una trasmissione, mostra semplicemente i byte come un numero intero con segno)
enumerazione E,en mostra questo come un'enumerazione, stampando il nome del valore se disponibile o il valore intero in caso contrario
ad es. (enum enumType) val_type = eValue2
esadecimale - minuscolo x, h mostra questo in notazione esadecimale minuscola (questa operazione non esegue una cast, mostra semplicemente i byte come esadecimale)
esadecimale - maiuscolo X, H mostra questa notazione esadecimale maiuscola (questa operazione non esegue una cast, mostra semplicemente i byte come esadecimale)
esadecimale - lettere minuscole, senza iniziali 0x xb, hb mostra questo in notazione esadecimale minuscola senza prefisso 0x (questa operazione non esegue una cast, mostra semplicemente i byte come esadecimale)
esadecimale - maiuscolo, senza iniziale 0x Xb, Hb mostra questo in notazione esadecimale maiuscola senza prefisso 0x (questa operazione non esegue una cast, mostra semplicemente i byte come esadecimale)
numero in virgola mobile f mostra questo come un numero in virgola mobile (questa operazione non esegue una trasmissione, ma interpreta semplicemente i byte come un valore in virgola mobile IEEE754)
ottale n mostra questo in notazione ottale
Tipo di sistema operativo O mostra questo come un MacOS OSType
ad es. (float) x = '\n\x1f\xd7\n'
stringa - Stringa del Do s mostra questa stringa come stringa C con 0,
ad es. "hello world"
stringa : la stringa Do, senza virgolette. sb mostra una stringa C con terminazione 0 senza virgolette,
ad es. hello world
stringa - UTF-8 S8 mostralo come stringa UTF-8 con terminazione 0
ad es. u8"hello world ☕"
stringa - UTF-8, senza virgolette S8B mostralo come stringa UTF-8 con terminazione 0 senza virgolette
ad esempio hello world ☕
stringa - UTF-16 su mostralo come stringa UTF-16 con terminazione 0
ad es. u"hello world ☕"
stringa - UTF-16, senza virgolette sub mostralo come stringa UTF-16 con terminazione 0 senza virgolette
ad esempio hello world ☕
stringa - UTF-32 S32 mostralo come stringa UTF-32 con terminazione 0
ad es. U"hello world ☕"
stringa - UTF-32, senza virgolette S32B mostralo come stringa UTF-32 con terminazione 0 senza virgolette
ad esempio hello world ☕
Unicode16 U mostra come caratteri UTF-16
ad es. (float) x = 0xd70a 0x411f
Unicode32 U32 mostra come caratteri UTF-32
ad es. (float) x = 0x411fd70a
decimale senza segno u mostra questo come un numero intero senza segno (questa operazione non esegue una trasmissione, mostra semplicemente i byte come un numero intero senza segno)
puntatore p mostra come puntatore nativo (a meno che non si tratti di un puntatore, l'indirizzo risultante probabilmente non sarà valido)
numero intero complesso I interpreta questo valore come la parte reale e immaginaria di un numero intero complesso
ad es. puntatore (int *) = 1048960 + 1i
array di caratteri a mostra questo come un array di caratteri
ad es. (char) *c.sp.z = {X}
Raw - Una cruda verità ! formato non elaborato, ignorando qualsiasi personalizzazione delle viste dei tipi di dati

Natvis

Il framework Natvis consente di personalizzare il modo in cui Visual Studio visualizza i tipi nativi nelle finestre delle variabili del debugger. Ad esempio, utilizza Natvis per personalizzare le visualizzazioni delle finestre Orologio, Locale e Suggerimenti sui dati.

La funzionalità Natvis è abilitata per impostazione predefinita, ma può essere disabilitata da Visual Studio impostando il flag Strumenti > Opzioni > Estensione per lo sviluppo dei giochi Android > Natvis su Disattivato.

Caricamento dei file Natvis in corso...

Visual Studio carica i file Natvis dalle tre posizioni elencate di seguito e li ricarica a ogni avvio di una sessione di debug. I file devono rispettare lo schema Natvis di Visual Studio 2017.

  • .natvis file che fanno parte di un progetto o di un elemento di soluzione di primo livello caricato.
  • La directory specifica dell'utente (%USERPROFILE%\Documents\Visual Studio 2017\Visualizers)
  • La directory a livello di sistema (%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers)
Ricaricamento dei file Natvis in corso...

Ricarica i file Natvis durante una sessione di debug valutando .natvisreload nella finestra di comando o di visualizzazione.

File Natvis di esempio

Questo file Natvis di esempio include tutti i tag e gli attributi attualmente supportati.

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

Creazione di file Natvis

Visual Studio supporta la creazione di file Natvis. Per ulteriori informazioni sulla personalizzazione delle finestre delle variabili del debugger, vedi MSDN.

Debug dei file Natvis

In alcuni casi gli errori vengono presentati come Valore di una variabile (ad es. nelle finestre Auto, Watch e così via). Ad esempio: <error: use of undeclared identifier 'missingVar'>

Puoi accedere a ulteriori dettagli sull'errore aprendo il file GoogleAndroid.log dalla barra degli strumenti dell'estensione per lo sviluppo di giochi Android.

Limitazioni note

  • Se il tag o l'attributo non è elencato nel file di esempio riportato sopra, significa che al momento non è supportato. Visual Studio ignora i tag e gli attributi non supportati, quindi puoi lasciarli in un file Natvis esistente e il file funzionerà, purché utilizzi il nostro schema.

  • L'attributo Usage, anche se obbligatorio dallo schema, non è supportato per <SmartPointer>. Tuttavia, LLDB non limita l'accesso agli operatori definiti in C++, perciò è possibile definire qualsiasi operatore richiesto in C++.