Eseguire il debug del codice Python in Visual Studio

Visual Studio offre un'esperienza di debug completa per Python. In questo articolo viene illustrato come collegare il debugger ai processi in esecuzione e valutare le espressioni nelle finestre Watch e Immediate. Nel debugger è possibile esaminare le variabili locali, usare punti di interruzione, istruzioni di passaggio/uscita/over, Imposta istruzione successiva e altro ancora.

Per informazioni sul debug specifico dello scenario, vedere gli articoli seguenti:

Prerequisiti

Eseguire il debug del codice con o senza un progetto

Per controllare l'ambiente e gli argomenti Python, crea prima un progetto per il tuo codice. È possibile creare un progetto con il modello di progetto Da codice Python esistente. Per altre informazioni, vedere Creare un progetto da file di codice di Python esistenti.

Tuttavia, non è necessario un file di progetto o di soluzione in Visual Studio per eseguire il debug del codice Python. Per eseguire il debug del codice in un file di Python autonomo, aprire il file in Visual Studio e selezionare Debug>Avvia debug. Visual Studio avvia lo script con l'ambiente predefinito globale e senza argomenti. È quindi disponibile il supporto completo del debug per il codice. Per altre informazioni, vedere ambienti Python.

Esplorare il debug di base

Il flusso di lavoro di debug di base prevede punti di interruzione delle impostazioni, esecuzione di istruzioni nel codice, controllo dei valori e gestione delle eccezioni. È possibile avviare una sessione di debug selezionando Debug>Avvia debug o usando il tasto di scelta rapida F5 . Per un progetto, queste azioni avviano il file startup con l'ambiente attivo del progetto e qualsiasi argomento della riga di comando o percorsi di ricerca specificati per le Proprietà del progetto. Per configurare le proprietà, vedere Impostare le opzioni di debug del progetto.

Impostare il file di avvio del progetto

Il file di avvio per un progetto viene visualizzato in grassetto in Esplora soluzioni. È possibile scegliere il file da usare come file di avvio.

  • Per specificare un file di progetto come file di avvio, fare clic con il pulsante destro del mouse sul file e scegliere Imposta come elemento di avvio.

In Visual Studio 2017 versione 15.6 e successive viene visualizzato un avviso se non si dispone di un set di file di avvio specificato. Le versioni precedenti di Visual Studio potrebbero aprire una finestra Output con l'interprete Python in esecuzione oppure la finestra Output si apre brevemente e chiude.

Specificare l'ambiente attivo

Se si usa un file di progetto, il debugger inizia sempre con l'ambiente di Python attivo per il progetto. È possibile modificare l'ambiente attivo corrente. Per altre informazioni, vedere Selezionare un ambiente Python per un progetto.

Se si esegue il debug di un file di codice Python autonomo, Visual Studio avvia lo script con l'ambiente predefinito globale e senza argomenti.

Impostare i punti di interruzione

I punti di interruzione arrestano l'esecuzione del codice in un punto contrassegnato in modo da poter controllare lo stato del programma.

Alcuni punti di interruzione in Python possono essere sorprendenti per gli sviluppatori che hanno lavorato con altri linguaggi di programmazione. In Python, l'intero file è codice eseguibile, quindi Python esegue il file quando viene caricato per elaborare qualsiasi definizione di classe o funzione di primo livello. Se è impostato un punto di interruzione, potresti trovare che il debugger si ferma a metà di una dichiarazione di classe. Questo comportamento è corretto, anche se a volte è sorprendente.

  • Per impostare un punto di interruzione, selezionare nel margine sinistro dell'editor di codice o fare clic con il pulsante destro del mouse su una riga di codice e selezionarePunto di interruzione Inserisci punto> di interruzione. Viene visualizzato un punto rosso su ogni riga con un punto di interruzione impostato.

  • Per rimuovere un punto di interruzione, selezionare il punto rosso o fare clic con il pulsante destro del mouse sulla riga di codice e selezionare Punto di interruzione>Elimina punto di interruzione. È anche possibile disabilitare un punto di interruzione selezionando il punto rosso e selezionando Disabilita punto> diinterruzione.

    Screenshot che mostra come disabilitare un punto di interruzione nel margine sinistro del file di codice in Visual Studio.

Impostare condizioni e azioni

È possibile personalizzare le condizioni in cui viene attivato un punto di interruzione, ad esempio l'interruzione solo quando una variabile è impostata su un determinato valore o intervallo di valori.

  • Per impostare le condizioni, fare clic con il pulsante destro del mouse sul punto rosso del punto di interruzione, selezionare Condizioni. Verrà visualizzata la finestra di dialogo Impostazioni punto di interruzione .

    Nella finestra di dialogo è possibile aggiungere più condizioni e creare espressioni condizionali usando Python codice. Per informazioni dettagliate su questa funzionalità in Visual Studio, vedere condizioni del punto di interruzione.

  • Sono disponibili anche le opzioni per impostare Azioni per un punto di interruzione. È possibile creare un messaggio per accedere alla finestra Output e, facoltativamente, specificare per continuare automaticamente l'esecuzione.

    La registrazione di un messaggio crea un punto di traccia che non aggiunge direttamente il codice di registrazione all'applicazione.

A seconda di come si configurano condizioni e azioni per un punto di interruzione, l'icona rossa nel margine sinistro cambia per indicare le impostazioni. È possibile che venga visualizzata la forma del punto, un timer dell'orologio o un rombo.

Eseguire il codice passo dopo passo

Quando Visual Studio arresta l'esecuzione del codice in un punto di interruzione, è possibile usare diversi comandi per scorrere il codice o eseguire blocchi di codice prima di interrompere di nuovo. I comandi sono disponibili in alcune posizioni in Visual Studio, tra cui la barra degli strumenti Debugger, il menu Debug, il menu contestuale del clic destro nell'editor di codice e tramite le scorciatoie da tastiera.

La tabella seguente riepiloga questi comandi e fornisce i tasti di scelta rapida:

Comando Shortcut Description
Stop MAIUSC + F5 Interrompere la sessione di debug.
Riavviare CTRL+ MAIUSC + F5 Riavviare la sessione di debug corrente.
Continuare F5 Eseguire il codice fino a raggiungere il punto di interruzione successivo.
Entra in F11 Esegui l'istruzione successiva e fermati. Se l'istruzione successiva è una chiamata a una funzione, il debugger si arresta alla prima riga della funzione chiamata.
Passa sopra F10 Eseguire l'istruzione successiva, inclusa l'esecuzione di una chiamata a una funzione (che esegue tutto il codice) e l'applicazione di qualsiasi valore restituito. Questo comando consente di ignorare facilmente le funzioni di cui non è necessario eseguire il debug.
Fai un passo fuori MAIUSC+F11 Eseguire il codice fino alla fine della funzione corrente, quindi passare all'istruzione chiamante. Questo comando è utile quando non è necessario eseguire il debug del resto della funzione corrente.
Esegui fino al cursore Ctrl+F10 Eseguire il codice fino alla posizione del caret nell'editor. Questo comando consente di ignorare facilmente un segmento di codice di cui non è necessario eseguire il debug.
Imposta la prossima istruzione Ctrl+Maiusc+F10 Modificare il punto di esecuzione corrente nel codice impostando la posizione del cursore. Questo comando consente di omettere un segmento di codice dall'esecuzione, ad esempio quando si sa che il codice è difettoso o produce un effetto collaterale indesiderato.
Mostra dichiarazione successiva Alt+Num+\ Tornare all'istruzione successiva da eseguire nel codice. Questo comando consente di individuare la posizione nel codice in cui viene arrestato il debugger.

Esaminare e modificare i valori

Quando si arresta l'esecuzione del codice nel debugger, è possibile esaminare e modificare i valori delle variabili. È anche possibile utilizzare la finestra Osservazione per monitorare singole variabili ed espressioni personalizzate. Per altre informazioni, vedere Esaminare le variabili.

  • Per visualizzare un valore usando la funzionalità Suggerimenti dati durante il debug, posizionare il puntatore del mouse su qualsiasi variabile nell'editor. È possibile selezionare il valore della variabile per modificarlo:

  • Per usare la finestra Autos, selezionare Debug>Windows>Autos. Questa finestra contiene variabili ed espressioni vicine all'istruzione corrente. È possibile fare doppio clic nella colonna valore oppure selezionare e immettere F2 per modificare il valore:

    Screenshot che mostra la finestra Auto nel debugger Visual Studio.

    Per altre informazioni sull'uso della finestra Auto, vedere Controllare le variabili nelle finestre Auto e Variabili locali.

  • Per usare la finestra Locals, selezionare Debug>Windows>Locals. In questa finestra vengono visualizzate tutte le variabili presenti nell'ambito corrente. È possibile fare doppio clic nella colonna valore oppure selezionare e immettere F2 per modificare il valore:

    Per altre informazioni sull'uso della finestra Variabili locali , vedere Controllare le variabili nelle finestre Auto e Variabili locali.

  • Per usare il Watch windows, selezionare Debug>Windows>Watch>Watch 1-4. Questa opzione consente di immettere espressioni arbitrarie Python e visualizzare i risultati. Le espressioni vengono rivalutate per ogni passaggio:

    Per altre informazioni sull'uso della finestra Espressione di controllo , vedere Impostare un controllo sulle variabili con le finestre Espressione di controllo e Controllo immediato.

  • Per esaminare un valore stringa, selezionare Visualizza (lente di ingrandimento) sul lato destro della voce Valore . I strtipi , unicodebytes, e bytearray sono tutti disponibili per l'ispezione.

    Il menu a discesa Visualizza visualizza quattro opzioni di visualizzazione: Testo, HTML, XML o JSON.

    Dopo aver selezionato una visualizzazione, una finestra di dialogo popup mostra il valore stringa senza virgolette in base al tipo selezionato. È possibile visualizzare la stringa con ritorno a capo e scorrimento, evidenziazione della sintassi e visualizzazioni albero. Queste visualizzazioni consentono di eseguire il debug di problemi con stringhe lunghe e complesse.

Visualizzare le eccezioni

Se si verifica un errore nel programma durante il debug, ma non si dispone di un gestore eccezioni, il debugger si interrompe al punto dell'eccezione:

Screenshot che mostra un popup di eccezione per un errore non gestito nel debugger di Visual Studio.

Screenshot che mostra una finestra popup di Eccezione per un errore non gestito nel debugger di Visual Studio.

Quando si verifica un errore, è possibile controllare lo stato corrente del programma, incluso lo stack di chiamate. Tuttavia, se si esegue un'istruzione dettagliata del codice, il processo di debug continua a generare l'eccezione fino a quando non viene gestito o il programma viene chiuso.

  • Per visualizzare una visualizzazione espansa delle eccezioni, selezionare Debug>Windows>Exception Settings.

    Nella finestra Impostazioni eccezioni la casella di controllo accanto a un'eccezione controlla se il debugger si interrompe sempre quando viene generata l'eccezione.

  • Per interrompere più spesso una particolare eccezione, selezionare la casella di controllo accanto all'eccezione nella finestra Impostazioni eccezioni .

  • Per impostazione predefinita, la maggior parte delle eccezioni si interrompe quando non è possibile trovare un gestore eccezioni nel codice sorgente. Per modificare questo comportamento, fare clic con il pulsante destro del mouse su qualsiasi eccezione e modificare l'opzione Continua quando non gestita nel codice utente . Per interrompere meno frequentemente in caso di eccezione, deselezionare questa opzione.

  • Per configurare un'eccezione che non viene visualizzata nella finestra Impostazioni eccezioni , selezionare Aggiungi (segno più). Immettere un nome per l'eccezione da monitorare. Il nome deve corrispondere al nome completo dell'eccezione.

Configurare le opzioni di debug del progetto

Per impostazione predefinita, il debugger avvia il programma con l'utilità di avvio standard Python, senza argomenti della riga di comando e senza altri percorsi o condizioni speciali. È possibile configurare le opzioni di avvio per un progetto Python impostando le proprietà di debug.

  • Per accedere alle proprietà di debug per un progetto, fare clic con il pulsante destro del mouse sul progetto Python in Esplora soluzioni, selezionare Proprietà e quindi selezionare la scheda Debug.

Le sezioni seguenti descrivono le proprietà specifiche.

Definire il comportamento di avvio

Nella tabella seguente sono elencati i valori possibili per la proprietà Modalità di avvio . Utilizzare questa proprietà per definire il comportamento di avvio per il debugger.

Value Description
Launcher Python Standard Usare il codice di debug scritto in Python portabile compatibile con CPython, IronPython e varianti come stackless Python. Questa opzione offre l'esperienza migliore per il debug di codice Python puro. Quando si esegue il collegamento a un processo python.exe in esecuzione, viene utilizzato il launcher specificato in questa proprietà. Questa utilità di avvio fornisce anche il debug in modalità di mix per CPython, che consente di passare facilmente tra codice C/C++ e codice Python.
Utilità di avvio Web Avviare il browser predefinito all'avvio e abilitare il debug dei modelli. Per altre informazioni, vedere la sezione Debug dei modelli Web .
Utilità di avvio Web Django Implementare lo stesso comportamento della proprietà dell'utilità di avvio Web, ma per un ambiente Django. Utilizzare questa opzione solo ai fini della compatibilità con le versioni precedenti.
Lanciatore IronPython (.NET) Usare il debugger .NET, che funziona solo con IronPython, ma consente l'esecuzione di istruzioni tra qualsiasi progetto di linguaggio .NET, incluso C# e Visual Basic. Questa utilità di avvio viene usata se si collega a un processo di .NET in esecuzione che ospita IronPython.

Definire il comportamento di esecuzione

Nella tabella seguente vengono descritte le proprietà che è possibile impostare per configurare il comportamento in esecuzione per il debugger.

Property Description
Percorsi di ricerca Specificare i percorsi di ricerca di file e cartelle Visual Studio usati per il progetto. Questi valori corrispondono agli elementi visualizzati nel nodo Search Paths nel nodo Esplora soluzioni. Sebbene sia possibile specificare i percorsi di ricerca in questa finestra di dialogo, può essere più semplice usare Esplora soluzioni, in cui è possibile esplorare le cartelle e convertire automaticamente i percorsi in un modulo relativo.
Argomenti script Definire gli argomenti da aggiungere al comando che Visual Studio utilizza per avviare il tuo script e che appaiono dopo il nome del file del tuo script. Il primo elemento elencato nel valore è disponibile per lo script come sys.argv[1], il secondo come sys.argv[2]e così via.
Argomenti dell'interprete Elenca gli argomenti da aggiungere alla riga di comando del launcher prima del nome dello script. Gli argomenti comuni sono -W ... controllare gli avvisi, -O ottimizzare leggermente il programma e -u usare operazioni di I/O non memorizzate nel buffer. È probabile che gli utenti di IronPython usino questo campo per passare -X opzioni, ad esempio -X:Frames o -X:MTA.
Percorso dell'interprete Identificare un percorso dell'interprete per eseguire l'override del percorso associato all'ambiente corrente. Il valore può essere utile per avviare lo script con un interprete non standard.
Variabili di ambiente Utilizzare questa proprietà per aggiungere voci del modulo <NAME>=\<VALUE>. Visual Studio applica questo valore di proprietà per ultimo, oltre a qualsiasi variabile di ambiente globale esistente e dopo PYTHONPATH viene impostato in base all'impostazione Search Paths. Di conseguenza, questa impostazione può essere usata per eseguire manualmente l'override di qualsiasi altra variabile.

Usare finestre interattive

Sono disponibili due finestre interactive che è possibile usare durante una sessione di debug: la finestra standard Visual Studio Immediate e la finestra Python Debug interattivo.

Aprire la finestra Immediata

È possibile usare la finestra standard Visual Studio Immediate per valutare rapidamente Python espressioni e controllare o assegnare variabili nel programma in esecuzione. Per altre informazioni, vedere Finestra Immediata.

  • Per aprire la finestra Immediate, selezionare Debug>Windows>Immediate. È anche possibile usare i tasti di scelta rapida CTRL+ALT+I.

Aprire la finestra Debug interattivo

La finestra Python Debug interattivo offre un ambiente completo con l'esperienza completa Interactive REPL disponibile durante il debug, inclusa la scrittura e l'esecuzione di codice. Questa finestra si connette automaticamente a qualsiasi processo avviato nel debugger usando l'utilità di avvio standard Python, inclusi i processi collegati tramite Debug>Attach a Processo. Tuttavia, questa finestra non è disponibile quando si usa il debug C/C++ in modalità mista.

  • Per usare la finestra Debug Interactive, selezionare Debug>Windows>Python Debug Interactive (Shift+Alt+I).

La finestra Debug interattivo supporta meta-comandi speciali oltre ai comandi REPL standard, come descritto nella tabella seguente:

Comando Description
$continue, $cont, $c Avviare l'esecuzione del programma dall'istruzione corrente.
$down, $d Spostare il frame corrente di un livello verso il basso nell'analisi dello stack.
$frame Visualizzare l'ID frame corrente.
$frame Passare il frame corrente all'ID frame specificato.
- Richiede un argomento <ID frame>.
$load Caricare i comandi dal file ed eseguire fino al completamento.
$proc Visualizzare l'ID del processo corrente.
$proc Cambia il processo corrente con l'ID processo specificato.
- Richiede un <ID processo> argomento.
$procs Elencare i processi attualmente in fase di debug.
$stepin, $step, $s Eseguire la chiamata di funzione successiva, se possibile.
$stepout, $return, $r Uscire dalla funzione corrente.
$stepover, $until, $unt Passa oltre la chiamata di funzione successiva.
$thread Visualizzare l'ID thread corrente.
$thread Passare il thread corrente all'ID thread specificato.
- Richiede un argomento <ID thread>.
$threads Elencare i thread in fase di debug.
$up, $u Spostare il frame corrente di un livello verso l'alto nella traccia dello stack.
$where, $w, $bt Elencare i frame per il thread corrente.

Le finestre del debugger standard, ad esempio Processi, Thread e Stack di chiamate , non vengono sincronizzate con la finestra Debug interattivo . Se si modifica il processo attivo, il thread o il frame nella finestra Debug interattivo , le altre finestre del debugger non sono interessate. Analogamente, la modifica del processo attivo, del thread o del frame nelle altre finestre del debugger non influisce sulla finestra Debug interattivo .

Usare il debugger legacy

A seconda della configurazione dell'ambiente, potrebbe essere necessario usare il debugger legacy:

  • Visual Studio 2017 versione 15.7 e precedenti con Python 2.6, da 3.1 a 3.4 o IronPython
  • Visual Studio 2019 versione 16.5 e successive con Python 2.6, da 3.1 a 3.4 o IronPython
  • ptvsd 3.x e versioni precedenti della versione 4.x

Il debugger legacy è il valore predefinito in Visual Studio 2017 versione 15.7 e precedenti.

  • Per usare il debugger legacy, selezionare Tools>Opzioni, espandere le opzioni Python>Debugging e selezionare l'opzione Use legacy debugger.

Supportare versioni precedenti di Visual Studio o di Python

Visual Studio 2017 versione 15.8 e successive usano un debugger basato su ptvsd versione 4.1 e successive. Visual Studio 2019 versione 16.5 e successive usano un debugger basato su debugpy. Queste due versioni del debugger sono compatibili con Python 2.7 o Python 3.5 e versioni successive.

Se si esegue una di queste versioni di Visual Studio, ma si usa Python 2.6, da 3.1 a 3.4 o IronPython, Visual Studio viene visualizzato l'errore Debugger non supporta questo ambiente Python:

Screenshot del messaggio di errore del debugger 'Debugger non supporta questo ambiente Python'.

Quando Visual Studio segnala questo errore di ambiente, è necessario usare il debugger legacy.

Supportare versioni ptvsd meno recenti

Se si usa una versione precedente di ptvsd nell'ambiente corrente ,ad esempio una versione 4.0.x precedente o una versione 3.x necessaria per il debug remoto, Visual Studio potrebbe visualizzare un errore o un avviso.

Se l'ambiente usa ptvsd 3.x, Visual Studio visualizza l'errore, non è stato possibile caricare il pacchetto Debugger:

Screenshot del messaggio di errore del debugger 'Impossibile caricare il pacchetto debugger'.

L'avviso, Il pacchetto debugger è obsoleto, viene visualizzato quando si usa una versione 4.x precedente di ptvsd:

Screenshot del messaggio di avviso del debugger

Quando Visual Studio segnala questi errori di ambiente, è necessario usare il debugger legacy.

Importante

Anche se è possibile scegliere di ignorare l'avviso per alcune versioni di ptvsd, Visual Studio potrebbe non funzionare correttamente.

Gestire l'installazione di ptvsd

Per gestire l'installazione di ptvsd, seguire questa procedura:

  1. Nella finestra Ambienti Python passare alla scheda Pacchetti.

  2. Immettere ptvsd nella casella di ricerca ed esaminare la versione installata di ptvsd:

  3. Se la versione è inferiore alla 4.1.1a9 (la versione in bundle con Visual Studio), selezionare il X a destra del pacchetto per disinstallare la versione precedente. Visual Studio quindi usa la versione in bundle. È anche possibile disinstallare da PowerShell usando il pip uninstall ptvsd comando .

  4. In alternativa, è possibile aggiornare il pacchetto ptvsd alla versione più recente seguendo le istruzioni nella sezione Risolvere i problemi relativi agli scenari di debug .

Risolvere i problemi relativi agli scenari di debug

Gli scenari seguenti descrivono altre opzioni di risoluzione dei problemi per la configurazione del debug.

Aggiornare ptvsd per Visual Studio 2019

Se si verificano problemi con il debugger in Visual Studio 2019 versione 16.4 e precedenti, aggiornare prima la versione del debugger come indicato di seguito:

  1. Nella finestra Ambienti Python passare alla scheda Pacchetti.

  2. Immettere ptvsd --upgrade nella casella di ricerca, quindi selezionare Esegui comando: pip install ptvsd --upgrade. È anche possibile usare lo stesso comando da PowerShell.

    Screenshot che illustra come selezionare il comando ptvsd upgrade nella finestra Python Environments.

    In caso di problemi persistenti, inviare un problema nel repository PTVS GitHub.

    Annotazioni

    Per Visual Studio 2019 versione 16.5 e successive, debugpy fa parte del carico di lavoro Visual Studio Python e viene aggiornato insieme a Visual Studio.

Abilitare la registrazione del debugger

Nel corso dell'analisi di un problema del debugger, Microsoft potrebbe chiedere di abilitare e raccogliere i log del debugger per facilitare la diagnosi.

La procedura seguente abilita il debug nella sessione di Visual Studio corrente:

  1. Aprire una finestra di comando in Visual Studio selezionando View>Other Windows>Command Window.

  2. Immettere il comando seguente:

    DebugAdapterHost.Logging /On /OutputWindow

  3. Avviare il debug ed eseguire i passaggi necessari per riprodurre il problema. Durante questo periodo, i log di debug vengono visualizzati nella finestra Output sotto Log dell'host dell'adattatore di debug. È quindi possibile copiare i log da tale finestra e incollarli in un GitHub problema, un messaggio di posta elettronica e così via.

  4. Se Visual Studio smette di rispondere o non è altrimenti possibile accedere alla finestra Output, riavviare Visual Studio, aprire una finestra di comando e immettere il comando seguente:

    DebugAdapterHost.Logging /On

  5. Avviare il debug e riprodurre di nuovo il problema. I log del debugger si trovano in %temp%\DebugAdapterHostLog.txt.

Contenuti correlati

  • Last updated on