Eseguire il debug del codice Python in Visual Studio

Articolo
04/18/2024

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 Espressioni di controllo e controllo immediato . 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

Visual Studio installato con il supporto per i carichi di lavoro Python. Per altre informazioni, vedere Installare il supporto python in Visual Studio.
Codice Python da usare con il debugger.

Eseguire il debug del codice con o senza un progetto

Se si vuole controllare l'ambiente e gli argomenti Python, creare prima di tutto un progetto per il codice. È possibile creare un progetto con il modello di progetto Di codice Python esistente. Per altre informazioni, vedere Creare un progetto da file di codice 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 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 di avvio con l'ambiente attivo del progetto e qualsiasi argomento della riga di comando o percorsi di ricerca specificati per Proprietà 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 e chiude brevemente.

Specificare l'ambiente attivo

Se si usa un file di progetto, il debugger inizia sempre con l'ambiente 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

Con i punti di interruzione l'esecuzione del codice viene arrestata in corrispondenza di un punto contrassegnato per consentire il controllo dello stato del programma.

Alcuni punti di interruzione in Python possono risultare sorprendenti per gli sviluppatori che hanno lavorato con altri linguaggi di programmazione. In Python l'intero file è codice eseguibile, di conseguenza Python esegue il file quando viene caricato per elaborare tutte le definizioni di classe o di funzione di primo livello. Se è impostato un punto di interruzione, è possibile trovare il debugger che causa un'interruzione in 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 selezionare Punto 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> di interruzione.

Impostare condizioni e azioni

È possibile personalizzare le condizioni per l'attivazione di un punto di interruzione, ad esempio per interrompere l'esecuzione solo quando una variabile viene impostata su un valore o su un intervallo di valori specifico.

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 Punto di interruzione Impostazioni.

Nella finestra di dialogo è possibile aggiungere più condizioni e creare espressioni condizionali usando il codice Python. Per informazioni dettagliate su questa funzionalità in Visual Studio, vedere Condizioni per i punti 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.

Esecuzione del codice un'istruzione alla volta

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 di scelta rapida del pulsante destro del mouse nell'editor di codice e i tasti di scelta rapida.

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

Comando	Collegamento	Descrizione
Continua	F5	Eseguire il codice fino a raggiungere il punto di interruzione successivo.
Esegui istruzione	F11	Eseguire l'istruzione successiva e arrestarla. Se l'istruzione successiva è una chiamata a una funzione, il debugger si arresta alla prima riga della funzione chiamata.
Esegui istruzione/routine	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.
Esci da istruzione/routine	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 della parte restante della funzione corrente.
Esegui fino al cursore	CTRL+F10	Eseguire il codice fino alla posizione del cursore nell'editor. Questo comando consente di ignorare facilmente un segmento di codice di cui non è necessario eseguire il debug.
Imposta istruzione successiva	CTRL+MAIUSC+F10	Modificare il punto di esecuzione corrente nel codice impostando la posizione del cursore. Questo comando consente di evitare l'esecuzione di un segmento di codice, ad esempio quando si sa già che contiene errori o produce effetti collaterali indesiderati.
Mostra istruzione 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 usare la finestra Espressione di controllo per monitorare singole variabili ed espressioni personalizzate. Per altre informazioni, vedere Esaminare le variabili.

Per visualizzare un valore usando la funzionalità Data Suggerimenti 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 Auto, selezionare Debug>di Windows>Auto. 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:

Per altre informazioni sull'uso della finestra Auto, vedere Controllare le variabili nelle finestre Auto e Variabili locali.
Per usare la finestra Variabili locali, selezionare Debug variabili locali di>Windows.> In questa finestra vengono visualizzate tutte le variabili presenti nell'ambito corrente, che possono essere modificate di nuovo:

Per altre informazioni sull'uso della finestra Variabili locali , vedere Controllare le variabili nelle finestre Auto e Variabili locali.
Per usare le finestre Espressioni di controllo, selezionare Debug>Di Windows>Watch>1-4. Questa opzione consente di immettere espressioni Python arbitrarie e visualizzare i risultati. Le espressioni vengono valutate nuovamente 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 , bytesunicode, 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 e non si dispone di un gestore di eccezioni per risolverlo, l'esecuzione del debugger si interrompe in corrispondenza del punto in cui si è verificata l'eccezione:

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>eccezione windows>Impostazioni.

Nella finestra Eccezioni Impostazioni 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 Eccezione Impostazioni.
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 una qualsiasi eccezione e modificare l'opzione Continua se non gestita nel codice utente. Per interrompere meno spesso l'eccezione, deselezionare questa opzione.
Per configurare un'eccezione che non viene visualizzata nella finestra Eccezione Impostazioni, selezionare Aggiungi (simbolo più). Immettere un nome per l'eccezione da controllare. 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 di Python, senza argomenti della riga di comando e 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, scegliere 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.

Valore	Descrizione
Utilità di avvio Python standard	Usare il codice di debug scritto in Python portatile compatibile con CPython, IronPython e varianti come Python senza stack. Questa opzione offre l'esperienza migliore per il debug di codice Python puro. Quando si esegue il collegamento a un processo in esecuzione `python.exe` , viene utilizzato l'utilità di avvio specificata in questa proprietà. Questa utilità di avvio offre anche il debug in modalità mista per CPython, che consente di eseguire facilmente il passaggio 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 un comportamento identico alla proprietà dell'utilità di avvio Web, ma per un ambiente Django. Utilizzare questa opzione solo ai fini della compatibilità con le versioni precedenti.
Utilità di avvio IronPython (.NET)	Usare il debugger .NET, che funziona solo con IronPython, ma consente l'esecuzione di istruzioni tra qualsiasi progetto di linguaggio .NET, tra cui C# e Visual Basic. Questa utilità di avvio viene usata se si esegue il collegamento a un processo .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.

Proprietà	Descrizione
Percorsi di ricerca	Specificare i percorsi di ricerca di file e cartelle usati da Visual Studio per il progetto. Questi valori corrispondono agli elementi visualizzati nel nodo Percorsi di ricerca del progetto in 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 dello script	Definire gli argomenti da aggiungere al comando usato da Visual Studio per avviare lo script e visualizzarli dopo il nome file dello 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	Elencare gli argomenti da aggiungere alla riga di comando dell'utilità di avvio 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 le opzioni di `-X`, 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 Percorsi di ricerca. Di conseguenza, questa impostazione può essere usata per eseguire manualmente l'override di qualsiasi altra variabile.

Usare finestre interattive

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

Aprire la finestra Immediata

È possibile usare la finestra immediata di Visual Studio standard per valutare rapidamente le espressioni Python ed esaminare o assegnare variabili nel programma in esecuzione. Per altre informazioni, vedere Finestra di controllo immediato.

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

Aprire la finestra Debug interattivo

La finestra Python Debug Interactive offre un ambiente avanzato con l'esperienza REPL interattiva completa 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 Python Standard, inclusi i processi collegati tramite Debug>Attach to Process. Tuttavia, questa finestra non è disponibile quando si usa il debug C/C++ in modalità mista.

Per usare la finestra Debug interattivo, selezionare Debug>interattivo debug Python windows>(MAIUSC+ALT+I).

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

Comando	Descrizione
`$continue`, `$cont`, `$c`	Avviare l'esecuzione del programma dall'istruzione corrente.
`$down`, `$d`	Sposta 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`	Passare il processo corrente all'ID processo specificato. - Richiede un <argomento ID> processo.
`$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`	Eseguire il passaggio della 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 verso l'alto il frame corrente un livello nell'analisi 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 è l'impostazione predefinita in Visual Studio 2017 versione 15.7 e precedenti.

Per usare il debugger legacy, selezionare Opzioni strumenti>, espandere le opzioni debug Python>e selezionare l'opzione Usa debugger legacy.

Supportare versioni precedenti di Visual Studio o 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 visualizza l'errore, 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, impossibile caricare il pacchetto debugger:

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

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:

Nella finestra Ambienti Python passare alla scheda Pacchetti .
Immettere ptvsd nella casella di ricerca ed esaminare la versione installata di ptvsd:
Se la versione è precedente a 4.1.1a9, ovvero la versione in bundle con Visual Studio, selezionare la X a destra del pacchetto per disinstallare la versione precedente. Visual Studio usa quindi la versione in bundle. È anche possibile disinstallare da PowerShell usando il pip uninstall ptvsd comando .
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:

Nella finestra Ambienti Python passare alla scheda Pacchetti .
Immettere ptvsd --upgrade nella casella di ricerca, quindi selezionare Esegui comando: pip install ptvsd --upgrade. È anche possibile usare lo stesso comando di PowerShell.

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

Nota

Per Visual Studio 2019 versione 16.5 e successive, debugpy fa parte del carico di lavoro Python di Visual Studio 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 corrente di Visual Studio:

Aprire una finestra di comando in Visual Studio selezionando Visualizza>altra finestra di comando di Windows.>

Immettere il comando seguente:

DebugAdapterHost.Logging /On /OutputWindow

Avviare il debug ed eseguire i passaggi necessari per riprodurre il problema. Mentre si eseguono queste operazioni, i log del debug vengono visualizzati nella finestra Output in Log dell'host dell'adattatore di debug. È quindi possibile copiare i log da tale finestra e incollarli in un problema di GitHub, un messaggio di posta elettronica e così via.
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
```
Avviare il debug e riprodurre di nuovo il problema. I log del debugger si trovano in %temp%\DebugAdapterHostLog.txt.

Condividi tramite

Eseguire il debug del codice Python in Visual Studio

Prerequisiti

Eseguire il debug del codice con o senza un progetto