Python-code op afstand debuggen op Linux in Visual Studio

In dit artikel leert u hoe u uw Visual Studio-installatie configureert ter ondersteuning van foutopsporing van Python-code op externe Linux-computers. Deze handleiding is gebaseerd op Visual Studio 2019 versie 16.6.

Visual Studio kan Python-toepassingen lokaal en extern op een Windows-computer starten en fouten opsporen. Visual Studio biedt ook ondersteuning voor foutopsporing op afstand op een ander besturingssysteem, apparaat of Python-implementatie dan CPython met behulp van de debugpy-bibliotheek.

Visual Studio 2019 versie 16.4 en eerder maakt gebruik van de ptvsd-bibliotheek. In Visual Studio 2019 versie 16.5 en later vervangt de bibliotheek debugpy ptvsd. Wanneer je debugpy gebruikt, host de Python-code die wordt gedebugd de debugeerver waaraan Visual Studio kan koppelen. Voor deze hosting is een kleine wijziging van uw code vereist om de server te importeren en in te schakelen. Mogelijk moet u ook de netwerk- of firewallconfiguraties op de externe computer aanpassen om TCP-verbindingen toe te staan.

Voorwaarden

• Visual Studio geïnstalleerd met ondersteuning voor Python-workloads. Zie Python-ondersteuning installeren in Visual Studiovoor meer informatie.

• Een externe computer met Python op een besturingssysteem, zoals macOS of Linux.

• Poort 5678 (inkomend) is geopend op de firewall van de externe computer. Dit is de standaardinstelling voor externe foutopsporing.

Een Linux-computer instellen

U kunt eenvoudig een virtuele Linux-machine maken in Azure en de machine openen met Extern bureaublad van Windows. Ubuntu voor de virtuele machine is handig omdat Python standaard is geïnstalleerd. Als u een andere configuratie hebt, raadpleegt u Python-interpreters installeren voor andere Python-downloadlocaties.

De firewall configureren

De binnenkomende poort 5678 moet zijn geopend op de firewall van de externe computer om externe foutopsporing te ondersteunen.

Zie de volgende artikelen voor meer informatie over het maken van een firewallregel voor een virtuele Azure-machine:

• netwerkverkeer filteren met een netwerkbeveiligingsgroep met behulp van azure Portal
• Netwerkverkeer routeren met een routetabel met behulp van azure Portal
• Azure Firewall implementeren en configureren met behulp van azure Portal

Het script voorbereiden voor foutopsporing

Volg deze stappen om een script voor te bereiden voor het opsporen van fouten in uw Python-code in Linux.

1. Maak op de externe computer een Python-bestand met de naam guessing-game.py met de volgende code:

   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. Installeer het debugpy-pakket in uw omgeving met behulp van de opdracht pip3 install debugpy.

   Notitie

   Het is een goed idee om de versie van foutopsporing op te nemen die is geïnstalleerd voor het geval u deze nodig hebt voor probleemoplossing. In de debugpy-lijst worden ook beschikbare versies weergegeven.

3. Schakel externe foutopsporing in door de volgende code boven aan het guessing-game.py-bestand toe te voegen vóór andere code. (Hoewel dit geen strikte vereiste is, is het onmogelijk om fouten op te sporen in achtergrondthreads die zijn opgespoord voordat de listen functie wordt aangeroepen.)

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

4. Sla het bestand op en voer het programma uit:

   python3 guessing-game.py
   

   De aanroep van de functie listen wordt op de achtergrond uitgevoerd en wacht op binnenkomende verbindingen terwijl u met het programma communiceert. Indien gewenst kunt u de wait_for_client functie aanroepen nadat u de listen-functie hebt aangeroepen om het programma te blokkeren totdat het foutopsporingsprogramma wordt gekoppeld.

Fooi

Naast de functies listen en wait_for_client biedt debugpy ook een helperfunctie breakpoint. Deze functie fungeert als een programmatisch onderbrekingspunt als het foutopsporingsprogramma is gekoppeld. Een andere functie, is_client_connected1, retourneert True als het foutopsporingsprogramma is gekoppeld. U hoeft dit resultaat niet te controleren voordat u andere debugpy functies aanroept.

Extern koppelen vanuit Python-hulpprogramma's

De volgende stappen laten zien hoe u een onderbrekingspunt instelt om het externe proces te stoppen.

1. Maak een kopie van het externe bestand op de lokale computer en open het in Visual Studio. Het maakt niet uit waar het bestand zich bevindt, maar de naam moet overeenkomen met de naam van het script op de externe computer.

2. (Optioneel) Als u IntelliSense wilt hebben voor foutopsporing op uw lokale computer, installeert u het foutopsporingspakket in uw Python-omgeving.

3. Selecteer Foutopsporing>Koppelen aan Proces.

4. Stel in het dialoogvenster Koppelen aan proces het verbindingstype in op Python remote (debugpy).

5. Voer in het veld Verbindingsdoel de opdracht tcp://<ip_address>:5678in.

   • tcp:// geeft het verbindingstype op als Transmission Control Protocol (TCP).
   • <ip_address> is het IP-adres van de externe computer, dat een expliciet adres of een naam zoals myvm.cloudapp.netkan zijn.
   • :5678 is het poortnummer voor externe foutopsporing.

6. Selecteer Voer in om de lijst met beschikbare foutopsporingsprocessen op die computer te vullen:

   

   Als u een ander programma op de externe computer start nadat u deze lijst hebt ingevuld, selecteert u de knop Vernieuwen.

7. Selecteer het proces om fouten op te sporen en selecteer bijvoegen of dubbelklik op het proces.

8. Visual Studio schakelt over naar de foutopsporingsmodus terwijl het script blijft worden uitgevoerd op de externe computer, wat alle gebruikelijke foutopsporing mogelijkheden biedt.

   U kunt een onderbrekingspunt instellen op de if guess < number: regel, vervolgens overschakelen naar de externe computer en een andere schatting invoeren. Visual Studio op uw lokale computer stopt bij het onderbrekingspunt, toont lokale variabelen, enzovoort:

   

9. Wanneer u de foutopsporing stopt, wordt het programma losgekoppeld van Visual Studio. Het programma wordt nog steeds uitgevoerd op de externe computer. debugpy blijft ook luisteren naar het koppelen van foutopsporingsprogramma's, zodat u op elk moment opnieuw een debugger aan het proces kunt koppelen.

Problemen met de verbinding oplossen

Bekijk de volgende punten om problemen met de verbinding op te lossen.

• Zorg ervoor dat u Python remote (debugpy) selecteert voor het verbindingstype.

• Bevestig dat het geheim in de verbindingsdoel exact overeenkomt met het geheim in de externe code.

• Controleer of het IP-adres in het verbindingsdoel overeenkomt met dat van de externe computer.

• Controleer of de poort voor externe foutopsporing op de externe computer is geopend en het verbindingsdoel het poortachtervoegsel bevat, zoals :5678.

  Als u een andere poort wilt gebruiken, geeft u het poortnummer op in de aanroep naar de functie listen, zoals in debugpy.listen((host, port)). In dit geval moet u de specifieke poort in de firewall openen.

• Controleer of de foutopsporingsversie die is geïnstalleerd op de externe computer (zoals geretourneerd door de opdracht pip3 list) overeenkomt met de PTVS-versie (Visual Studio Python Tools).

  De volgende tabel bevat de geldige versieparen. Werk indien nodig de versie van debugpy op de externe computer bij.

  Visual Studio	Python-hulpprogramma's	debugpy
  2019 16.6	1.0.0b5	1.0.0b5
  2019 16.5	1.0.0b1	1.0.0b1

Notitie

Visual Studio 2019 versie 16.0-16.4 gebruikte ptvsd, niet debugpy. Het proces in dit scenario voor deze versies is vergelijkbaar, maar de functienamen verschillen. Visual Studio 2019 versie 16.5 maakt gebruik van foutopsporing, maar de functienamen waren hetzelfde als die in ptvsd. In plaats van listenzou u enable_attachgebruiken. In plaats van wait_for_clientzou u wait_for_attachgebruiken. In plaats van breakpointzou u break_into_debuggergebruiken.

Ptvsd 3.x gebruiken voor verouderde foutopsporing

Het verouderde foutopsporingsprogramma ptvsd 3.x is de standaardinstelling in Visual Studio 2017 versie 15.7 en eerder.

Afhankelijk van uw Visual Studio-configuratie moet u mogelijk ptvsd 3.x gebruiken voor externe foutopsporing:

• Visual Studio 2017 versie 15.7 en eerder met Python 2.6, 3.1 tot 3.4 of IronPython
• Visual Studio 2019 versie 16.5 en hoger met Python 2.6, 3.1 tot 3.4 of IronPython
• Vroege 4.x-versies

Als uw configuratie een ouder versiescenario implementeert, wordt in Visual Studio de fout weergegeven, Foutopsporingsprogramma geen ondersteuning biedt voor deze Python-omgeving.

Externe foutopsporing instellen

Voer de volgende stappen uit om u voor te bereiden op externe foutopsporing met ptvsd 3.x:

1. Stel uw geheim in, dat wordt gebruikt om de toegang tot het actieve script te beperken.

   In ptvsd 3.x moet u voor de functie enable_attach een 'geheim' doorgeven als het eerste argument.

   • Wanneer u het externe foutopsporingsprogramma koppelt, voert u het geheim in met de opdracht enable_attach(secret="<secret>").

   Hoewel u iedereen kunt toestaan verbinding te maken met behulp van de opdracht enable_attach(secret=None), wordt deze optie niet aanbevolen.

2. Maak de doel-URL van de verbinding in het formulier tcp://<secret>@<ip_address>:5678.

   • tcp:// geeft het verbindingstype op als TCP.
   • <secret> is de tekenreeks die wordt doorgegeven met de enable_attach functie in de Python-code.
   • <ip_address> is het IP-adres van de externe computer, dat een expliciet adres of een naam zoals myvm.cloudapp.netkan zijn.
   • :5678 is het poortnummer voor externe foutopsporing.

Beveiligde verbinding met TCPS-protocol

Standaard wordt de verbinding met de ptvsd 3.x externe foutopsporingsserver alleen beveiligd door het geheim en worden alle gegevens doorgegeven in tekst zonder opmaak. Voor een veiligere verbinding ondersteunt ptvsd 3.x SSL met behulp van de beveiligde vorm van het TCP-protocol of TCPS-.

Gebruik de volgende stappen om ptvsd 3.x te configureren voor gebruik met het TCPS-protocol:

1. Gebruik op de externe computer de opdracht openssl om afzonderlijke bestanden voor de sleutel en het zelfondertekende certificaat te genereren:

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

   • Voer bij de openssl prompt de hostnaam of het IP-adres in waarmee u verbinding maakt voor de Algemene naam.

   Zie Zelfondertekende certificaten in de documentatie van de Python ssl-module voor meer informatie. Houd er rekening mee dat met de opdracht die wordt beschreven in de Python-documentatie slechts één gecombineerd bestand wordt gegenereerd.

2. Wijzig in de code de aanroep van de functie enable_attach om certfile en keyfile argumenten op te nemen met behulp van de bestandsnamen als de waarden. Deze argumenten hebben dezelfde betekenis als voor de standaardfunctie ssl.wrap_socket Python.

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

   U kunt ook dezelfde wijziging aanbrengen in het codebestand op de lokale computer. Omdat deze code niet daadwerkelijk wordt uitgevoerd, is deze niet strikt noodzakelijk.

3. Start het Python-programma opnieuw op de externe computer, zodat het klaar is voor foutopsporing.

4. Het kanaal beveiligen door het certificaat toe te voegen aan Vertrouwde Root-CA op de Windows-computer met Visual Studio:

   1. Kopieer het certificaatbestand van de externe computer naar de lokale computer.

   2. Open Configuratiescherm en ga naar Windows Tools>Computercertificaten beheren.

   3. Vouw in het certlm [Certificaten - lokale computer] dialoogvenster het knooppunt Vertrouwde basiscertificeringsinstanties uit, klik met de rechtermuisknop op Certificatenen selecteer Alle taken>Importeren.

   4. Blader naar en selecteer het .cer bestand dat is gekopieerd van de externe computer.

   5. Ga door met de aanwijzingen in het dialoogvenster om het importproces te voltooien.

5. Herhaal het bijlageproces in Visual Studio, zoals eerder beschreven in Extern bijvoegen vanuit Python Tools.

   Definieer in dit geval tcps:// als het protocol voor de Verbindingsdoel (of Kwalificatie).

   

Verbindingsproblemen oplossen

Tijdens de verbindingspoging kan Visual Studio problemen ondervinden. Bekijk de volgende scenario's en voer de juiste actie uit, indien nodig.

• Visual Studio waarschuwt voor mogelijke certificaatproblemen bij het maken van verbinding via SSL.

  actie: u kunt het bericht negeren en doorgaan.

  Voorzichtigheid

  Houd er rekening mee dat hoewel het kanaal nog steeds is versleuteld tegen afluisteren, het open kan zijn voor man-in-the-middle-aanvallen.

• Visual Studio geeft de waarschuwing dat het externe certificaat niet wordt vertrouwd.

  probleem: het certificaat wordt niet correct toegevoegd aan de vertrouwde basis-CA.

  Actie: controleer de stappen om het certificaat toe te voegen aan vertrouwde basis-CA op de Windows-computer opnieuwen probeer de verbinding opnieuw uit te voeren.

  

• Visual Studio geeft de waarschuwing dat de naam van het externe certificaat niet overeenkomt met de hostnaam.

  probleem: de juiste hostnaam of het juiste IP-adres is niet opgegeven voor de algemene naam voor het certificaat.

  Actie: controleer de stappen in De verbinding beveiligen met TCPS-opnieuw. Zorg ervoor dat u de juiste Algemene naam gebruikt wanneer u het certificaat maakt en probeer de verbinding opnieuw uit te voeren.

  

Verwante inhoud

• foutopsporing op afstand