Eseguire il debug remoto del codice Python in Linux in Visual Studio

Questo articolo illustra come configurare l'installazione di Visual Studio per supportare il debug del codice Python in computer Linux remoti. Questa procedura dettagliata si basa su Visual Studio 2019 versione 16.6.

Visual Studio può avviare ed eseguire il debug di applicazioni Python in locale e in remoto in un computer Windows. Visual Studio supporta anche il debug in remoto in un sistema operativo, un dispositivo o un'implementazione Python diversa da CPython usando la libreria debugpy .

Visual Studio 2019 versione 16.4 e versioni precedenti usa la libreria ptvsd. In Visual Studio 2019 versione 16.5 e successive la libreria debugpy sostituisce ptvsd. Quando si usa debugpy, il codice Python sottoposto a debug ospita il server di debug a cui è possibile collegare Visual Studio. Questo hosting richiede una piccola modifica al codice per importare e abilitare il server. Potrebbe anche essere necessario modificare le configurazioni di rete o firewall nel computer remoto per consentire le connessioni TCP.

Prerequisiti

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

• Un computer remoto che esegue Python in un sistema operativo come macOS o Linux.

• La porta 5678 (in ingresso) viene aperta nel firewall del computer remoto, ovvero l'impostazione predefinita per il debug remoto.

Configurare un computer Linux

È possibile creare facilmente una macchina virtuale Linux in Azure e accedervi usando Desktop remoto da Windows. Ubuntu per la macchina virtuale è utile perché Python è installato per impostazione predefinita. Se si dispone di una configurazione diversa, vedere Installare interpreti Python per altri percorsi di download di Python.

Configurare il firewall

La porta in ingresso 5678 deve essere aperta nel firewall del computer remoto per supportare il debug remoto.

Per informazioni dettagliate su come creare una regola del firewall per una macchina virtuale di Azure, vedere gli articoli seguenti:

• Filtrare il traffico di rete con un gruppo di sicurezza di rete usando il portale di Azure
• Instradare il traffico di rete con una tabella di route usando il portale di Azure
• Distribuire e configurare Firewall di Azure usando il portale di Azure

Preparare lo script per il debug

Seguire questa procedura per preparare uno script per il debug del codice Python in Linux.

1. Nel computer remoto creare un file Python denominato guessing-game.py con il codice seguente:

   import random
   
   guesses_made = 0
   name = input('Hello! What is your name?\n')
   number = random.randint(1, 20)
   print('Well, {0}, I am thinking of a number between 1 and 20.'.format(name))
   
   while guesses_made < 6:
       guess = int(input('Take a guess: '))
       guesses_made += 1
       if guess < number:
           print('Your guess is too low.')
       if guess > number:
           print('Your guess is too high.')
       if guess == number:
           break
   if guess == number:
       print('Good job, {0}! You guessed my number in {1} guesses!'.format(name, guesses_made))
   else:
       print('Nope. The number I was thinking of was {0}'.format(number))
   

2. Installare il pacchetto debugpy nell'ambiente usando il comando pip3 install debugpy.

   Nota

   È consigliabile registrare la versione di debugpy installata nel caso in cui sia necessaria per la risoluzione dei problemi. L'elenco debugpy mostra anche le versioni disponibili.

3. Abilitare il debug remoto aggiungendo il codice seguente all'inizio del file guessing-game.py prima di altro codice. Sebbene non sia un requisito rigoroso, è impossibile eseguire il debug di tutti i thread in background generati prima che venga chiamata la funzione listen.

   import debugpy
   debugpy.listen(('0.0.0.0', 5678))
   

4. Salvare il file ed eseguire il programma:

   python3 guessing-game.py
   

   La chiamata alla funzione listen viene eseguita in background e attende le connessioni in ingresso durante l'interazione con il programma. Se lo si desidera, è possibile chiamare la funzione wait_for_client dopo aver chiamato la funzione listen per bloccare il programma fino a quando il debugger non viene collegato.

Mancia

Oltre alle funzioni di listen e wait_for_client, debugpy fornisce anche una funzione helper breakpoint. Questa funzione funge da punto di interruzione a livello di codice se il debugger è collegato. Un'altra funzione, is_client_connected1, restituisce True se il debugger è collegato. Non è necessario controllare questo risultato prima di chiamare altre funzioni di debugpy.

Collegare da remoto dagli strumenti Python

I passaggi seguenti illustrano come impostare un punto di interruzione per arrestare il processo remoto.

1. Creare una copia del file remoto nel computer locale e aprirla in Visual Studio. Non importa dove si trova il file, ma il nome deve corrispondere al nome dello script nel computer remoto.

2. (Facoltativo) Per avere IntelliSense per debugpy nel computer locale, installare il pacchetto debugpy nell'ambiente Python.

3. Selezionare Debug>Collega al processo.

4. Nella finestra di dialogo Collega a processo impostare Tipo di connessione su Python remoto (debugpy).

5. Nel campo Destinazione connessione immettere il comando tcp://<ip_address>:5678.

   • tcp:// specifica il tipo di connessione come TCP (Transmission Control Protocol).
   • <ip_address> è l'indirizzo IP del computer remoto, che può essere un indirizzo esplicito o un nome come myvm.cloudapp.net.
   • :5678 è il numero di porta di debug remoto.

6. Selezionare Immettere per popolare l'elenco dei processi debugpy disponibili nel computer:

   

   Se capita di avviare un altro programma sul computer remoto dopo aver popolato questo elenco, selezionare il pulsante Aggiorna.

7. Selezionare il processo da collegare per il debug e fare clic su Allegaoppure fare doppio clic sul processo.

8. Visual Studio passa alla modalità di debug mentre lo script continua a essere eseguito nel computer remoto, fornendo tutte le normali funzionalità di debug .

   È possibile impostare un punto di interruzione nella riga if guess < number:, quindi passare al computer remoto e immettere un'altra ipotesi. Visual Studio nel computer locale si arresta nel punto di interruzione, mostra le variabili locali e così via:

   

9. Quando si arresta il debug, Visual Studio si disconnette dal programma. Il programma continua a essere eseguito nel computer remoto. debugpy continua anche l'ascolto per il collegamento dei debugger, in modo da poter ricollegare il processo in qualsiasi momento.

Risolvere i problemi di connessione

Esaminare i punti seguenti per risolvere i problemi relativi alla connessione.

• Assicurarsi di selezionare Python remote (debugpy) per il Tipo di connessione.

• Verificare che il segreto nella Destinazione connessione corrisponda esattamente al segreto nel codice remoto.

• Verificare che l'indirizzo IP nella connessione alla destinazione corrisponda a quello del computer remoto.

• Verificare che la porta di debug remoto nel computer remoto sia aperta e che la destinazione di connessione includa il suffisso della porta, ad esempio :5678.

  Per usare una porta diversa, specificare il numero di porta nella chiamata alla funzione listen, come in debugpy.listen((host, port)). In questo caso, assicurarsi di aprire la porta specifica nel firewall.

• Verificare che la versione di debugpy installata nel computer remoto (come restituito dal comando pip3 list) corrisponda alla versione di Visual Studio Python Tools (PTVS).

  Nella tabella seguente sono elencate le coppie di versione valide. Se necessario, aggiornare la versione di debugpy nel computer remoto.

  Visual Studio	Strumenti Python	debugpy
  2019 16.6	1.0.0b5	1.0.0b5
  2019 16.5	1.0.0b1	1.0.0b1

Nota

Visual Studio 2019 versione 16.0-16.4 ha usato ptvsd, non debugpy. Il processo in questa procedura dettagliata per tali versioni è simile, ma i nomi delle funzioni sono diversi. Visual Studio 2019 versione 16.5 usa debugpy, ma i nomi delle funzioni sono uguali a quelli in ptvsd. Anziché listen, è possibile usare enable_attach. Anziché wait_for_client, è possibile usare wait_for_attach. Anziché breakpoint, è possibile usare break_into_debugger.

Usare ptvsd 3.x per il debug legacy

Il debugger legacy ptvsd 3.x è l'impostazione predefinita in Visual Studio 2017 versione 15.7 e precedenti.

A seconda della configurazione di Visual Studio, potrebbe essere necessario usare ptvsd 3.x per il debug remoto:

• 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
• Versioni precedenti della versione 4.x

Se la configurazione implementa uno scenario di versione precedente, Visual Studio visualizza l'errore Debugger non supporta questo ambiente Python.

Configurare il debug remoto

Per preparare il debug remoto con ptvsd 3.x, completare i passaggi seguenti:

1. Configurare il segreto, usato per limitare l'accesso allo script in esecuzione.

   In ptvsd 3.x, la funzione enable_attach richiede di passare un "segreto" come primo argomento.

   • Quando si collega il debugger remoto, immettere il segreto con il comando enable_attach(secret="<secret>").

   Sebbene sia possibile consentire a chiunque di connettersi usando il comando enable_attach(secret=None), questa opzione non è consigliata.

2. Creare l'URL di destinazione della connessione nel formato tcp://<secret>@<ip_address>:5678.

   • tcp:// specifica il tipo di connessione come TCP.
   • <secret> è la stringa passata con la funzione enable_attach nel codice Python.
   • <ip_address> è l'indirizzo IP del computer remoto, che può essere un indirizzo esplicito o un nome come myvm.cloudapp.net.
   • :5678 è il numero di porta di debug remoto.

Connessione sicura con il protocollo TCPS

Per impostazione predefinita, la connessione al server di debug remoto ptvsd 3.x è protetta solo dal segreto e tutti i dati vengono passati in testo normale. Per una connessione più sicura, ptvsd 3.x supporta SSL usando il formato sicuro del protocollo TCP o TCPS.

Per configurare ptvsd 3.x per usare il protocollo TCPS, seguire questa procedura:

1. Nel computer remoto usare il comando openssl per generare file separati per la chiave e il certificato autofirmato:

   openssl req -new -x509 -days 365 -nodes -out cert.cer -keyout cert.key
   

   • Al prompt openssl, immettere il nome host o l'indirizzo IP utilizzato per connettersi al Nome Comune .

   Per ulteriori informazioni, vedere certificati autofirmati nella documentazione del modulo Python ssl. Si noti che il comando descritto nella documentazione di Python genera solo un singolo file combinato.

2. Nel codice modificare la chiamata alla funzione enable_attach per includere argomenti certfile e keyfile usando i nomi file come valori. Questi argomenti hanno lo stesso significato di per la funzione Standard ssl.wrap_socket Python.

   ptvsd.enable_attach(secret='my_secret', certfile='cert.cer', keyfile='cert.key')
   

   È anche possibile apportare la stessa modifica nel file di codice nel computer locale. Poiché questo codice non viene effettivamente eseguito, non è strettamente necessario.

3. Riavviare il programma Python nel computer remoto in modo che sia pronto per il debug.

4. Proteggi il canale aggiungendo il certificato all'Autorità di Certificazione Radice Attendibile sul computer Windows con Visual Studio.

   1. Copiare il file del certificato dal computer remoto nel computer locale.

   2. Aprire Pannello di controllo e passare a Strumenti di Windows>Gestisci certificati computer.

   3. Nella finestra di dialogo certlm [Certificati - computer locale], espandere il nodo Autorità di Certificazione Radice Attendibili, fare clic con il pulsante destro del mouse su Certificatie selezionare Tutte le attività>Importa.

   4. Passare al file .cer copiato dal computer remoto e selezionarlo.

   5. Continuare con la finestra di dialogo per completare il processo di importazione.

5. Ripetere il processo di collegamento in Visual Studio, come descritto in precedenza in Collega in remoto da Python Tools.

   Per questa istanza, definire tcps:// come protocollo per il target di connessione (o qualificatore ).

   

Risolvere i problemi di connessione

Durante il tentativo di connessione, Visual Studio potrebbe riscontrare problemi. Esaminare gli scenari seguenti e intervenire in base alle esigenze.

• Visual Studio segnala potenziali problemi di certificato durante la connessione tramite SSL.

  Azione: È possibile ignorare il messaggio e continuare.

  Cautela

  Tenere presente che, anche se il canale è ancora crittografato contro l'intercettazione, può essere vulnerabile agli attacchi di tipo man-in-the-middle.

• Visual Studio visualizza l'avviso: "il certificato remoto non è attendibile".

  problema: il certificato non viene aggiunto correttamente alla CA radice attendibile.

  'azione: controllare di nuovo i passaggi per aggiungere il certificato alla CA radice attendibile nel computer Windowse riprovare la connessione.

  

• Visual Studio visualizza l'avviso che il nome del certificato remoto non corrisponde al nome host.

  problema: il nome host o l'indirizzo IP corretto non è specificato per il nome comune per il certificato.

  Azione: Ricontrollare i passaggi in Proteggere la connessione con TCPS. Assicurarsi di usare il nome comune corretto quando si crea il certificato e riprovare la connessione.

  

Contenuto correlato

• debug remoto