Remotedebugging von Python-Code unter Linux in Visual Studio

In diesem Artikel erfahren Sie, wie Sie Ihre Visual Studio-Installation so konfigurieren, dass das Debuggen von Python-Code auf Remote-Linux-Computern unterstützt wird. Diese exemplarische Vorgehensweise basiert auf Visual Studio 2019, Version 16.6.

Visual Studio kann Python-Anwendungen lokal und remote auf einem Windows-Computer starten und debuggen. Visual Studio unterstützt außerdem das Remotedebugging auf einem anderen Betriebssystem, Gerät oder Python als CPython mithilfe der debugpy library.

Visual Studio 2019, Version 16.4 und früher, verwendet die ptvsd-Bibliothek. In Visual Studio 2019, Version 16.5 und höher, ersetzt die Debugpy-Bibliothek ptvsd. Wenn Sie debugpy verwenden, hostet der python-Code, der gedebuggt wird, den Debugserver, an den Visual Studio angefügt werden kann. Für dieses Hosting ist eine kleine Änderung des Codes erforderlich, um den Server zu importieren und zu aktivieren. Möglicherweise müssen Sie auch die Netzwerk- oder Firewallkonfigurationen auf dem Remotecomputer anpassen, um TCP-Verbindungen zuzulassen.

Voraussetzungen

• Visual Studio mit Unterstützung für Python-Workloads installiert. Weitere Informationen finden Sie unter Installieren der Python-Unterstützung in Visual Studio.

• Ein Remotecomputer, auf dem Python auf einem Betriebssystem wie macOS oder Linux ausgeführt wird.

• Port 5678 (eingehend) wird auf der Firewall des Remotecomputers geöffnet, was die Standardeinstellung für das Remotedebugging ist.

Einrichten eines Linux-Computers

Sie können auf einfache Weise einen virtuellen Linux-Computer auf Azure erstellen und mithilfe von Remotedesktop- von Windows darauf zugreifen. Ubuntu für den virtuellen Computer ist praktisch, da Python standardmäßig installiert ist. Wenn Sie über eine andere Konfiguration verfügen, lesen Sie Installieren von Python-Interpretern für andere Optionen zum Herunterladen von Python.

Konfigurieren der Firewall

Der eingehende Port 5678 muss auf der Firewall des Remotecomputers geöffnet sein, um das Remotedebugging zu unterstützen.

Ausführliche Informationen zum Erstellen einer Firewallregel für einen virtuellen Azure-Computer finden Sie in den folgenden Artikeln:

• Filtern des Netzwerkdatenverkehrs mit einer Netzwerksicherheitsgruppe mithilfe des Azure-Portals
• Routen Sie den Netzwerkdatenverkehr mit einer Routentabelle, indem Sie das Azure-Portal verwenden
• Bereitstellen und Konfigurieren der Azure-Firewall mithilfe des Azure-Portals

Vorbereiten des Skripts für das Debuggen

Führen Sie die folgenden Schritte aus, um ein Skript zum Debuggen Ihres Python-Codes unter Linux vorzubereiten.

1. Erstellen Sie auf dem Remotecomputer eine Python-Datei mit dem Namen guessing-game.py mit dem folgenden 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. Installieren Sie das debugpy-Paket mithilfe des Befehls pip3 install debugpy in Ihrer Umgebung.

   Anmerkung

   Es empfiehlt sich, die Version von Debugpy aufzuzeichnen, die installiert ist, falls Sie sie für die Problembehandlung benötigen. Die Debugpy-Auflistung zeigt auch verfügbare Versionen an.

3. Aktivieren Sie das Remotedebugging, indem Sie den folgenden Code oben in der guessing-game.py Datei vor einem anderen Code hinzufügen. (Obwohl keine strenge Anforderung, ist es unmöglich, alle Hintergrundthreads zu debuggen, die vor dem Aufrufen der listen-Funktion spawniert wurden.)

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

4. Speichern Sie die Datei, und führen Sie das Programm aus:

   python3 guessing-game.py
   

   Der Aufruf der listen-Funktion wird im Hintergrund ausgeführt und wartet während der Interaktion mit dem Programm auf eingehende Verbindungen. Wenn gewünscht, können Sie die wait_for_client-Funktion aufrufen, nachdem Sie die listen-Funktion aufgerufen haben, um das Programm anzuhalten, bis der Debugger angehängt wird.

Tipp

Zusätzlich zu den funktionen listen und wait_for_client bietet debugpy auch eine Hilfsfunktion breakpoint. Diese Funktion dient als programmgesteuerter Haltepunkt, wenn der Debugger angehängt ist. Eine andere Funktion, is_client_connected1, gibt True zurück, wenn der Debugger angefügt ist. Sie müssen dieses Ergebnis nicht überprüfen, bevor Sie andere debugpy Funktionen aufrufen.

Remoteanfügen über Python Tools

Die folgenden Schritte zeigen, wie Sie einen Haltepunkt festlegen, um den Remotevorgang zu beenden.

1. Erstellen Sie eine Kopie der Remotedatei auf dem lokalen Computer, und öffnen Sie sie in Visual Studio. Es spielt keine Rolle, wo sich die Datei befindet, aber der Name sollte mit dem Namen des Skripts auf dem Remotecomputer übereinstimmen.

2. (Optional) Um IntelliSense für Debugpy auf Ihrem lokalen Computer zu verwenden, installieren Sie das Debugpy-Paket in Ihrer Python-Umgebung.

3. Wählen Sie Debuggen>An den Prozess anhängen aus.

4. Legen Sie im Dialogfeld An den Prozess anhängen den Verbindungstyp auf Python remote (debugpy) fest.

5. Geben Sie im Feld Verbindungsziel- den Befehl tcp://<ip_address>:5678ein.

   • tcp:// gibt den Verbindungstyp als Transmission Control Protocol (TCP) an.
   • <ip_address> ist die IP-Adresse des Remotecomputers, die eine explizite Adresse oder ein Name wie myvm.cloudapp.netsein kann.
   • :5678 ist die Portnummer des Remotedebuggings.

6. Wählen Sie Geben Sie ein, um die Liste der verfügbaren Debugpy-Prozesse auf diesem Computer aufzufüllen:

   

   Wenn Sie nach dem Auffüllen dieser Liste ein anderes Programm auf dem Remotecomputer starten, wählen Sie die Schaltfläche Aktualisieren aus.

7. Wählen Sie den zu debuggenden Prozess, und klicken Sie auf Anfügenoder doppelklicken Sie auf den Prozess.

8. Visual Studio wechselt in den Debugmodus, während das Skript weiterhin auf dem Remotecomputer ausgeführt wird und alle üblichen Debugfunktionen bereitstellt.

   Sie können einen Haltepunkt auf der if guess < number: Zeile festlegen, dann auf den Remotecomputer wechseln und einen anderen Schätzwert eingeben. Visual Studio auf Ihrem lokalen Computer hält am Haltepunkt an, zeigt lokale Variablen usw.:

   

9. Wenn Sie das Debuggen beenden, trennt sich Visual Studio vom Programm. Das Programm wird weiterhin auf dem Remotecomputer ausgeführt. debugpy lauscht außerdem weiterhin auf angefügte Debugger, sodass Sie den Prozess jederzeit erneut wieder anfügen können.

Behandeln von Verbindungsproblemen

Überprüfen Sie die folgenden Punkte, um Probleme mit der Verbindung zu beheben.

• Stellen Sie sicher, dass Sie "Python Remote (debugpy)" für den Verbindungstypauswählen.

• Überprüfen Sie, ob das Geheimnis im Verbindungsziel genau mit dem Geheimnis im Remotecode übereinstimmt.

• Vergewissern Sie sich, dass die IP-Adresse im Verbindungsziel dem des Remotecomputers entspricht.

• Überprüfen Sie, ob der Remotedebuggingport auf dem Remotecomputer geöffnet ist, und ob das Verbindungsziel das Portsuffix, z. B. :5678, enthält.

  Um einen anderen Port zu verwenden, geben Sie die Portnummer im Aufruf der listen-Funktion wie in debugpy.listen((host, port))an. Achten Sie in diesem Fall darauf, den spezifischen Port in der Firewall zu öffnen.

• Vergewissern Sie sich, dass die auf dem Remotecomputer installierte Debugversion (wie vom pip3 list-Befehl zurückgegeben) mit der PtVS-Version (Visual Studio Python Tools) übereinstimmt.

  In der folgenden Tabelle sind die gültigen Versionspaare aufgeführt. Aktualisieren Sie bei Bedarf die Version von debugpy auf dem Remotecomputer.

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

Anmerkung

Visual Studio 2019, Version 16.0-16.4, verwendet ptvsd, nicht debugpy. Der Prozess in dieser exemplarischen Vorgehensweise für diese Versionen ist ähnlich, aber die Funktionsnamen sind unterschiedlich. Visual Studio 2019, Version 16.5, verwendet Debugpy, aber die Funktionsnamen waren identisch mit denen in ptvsd. Statt listenwürden Sie enable_attachverwenden. Statt wait_for_clientwürden Sie wait_for_attachverwenden. Statt breakpointwürden Sie break_into_debuggerverwenden.

Verwenden Sie ptvsd 3.x für Legacy-Debugging

Der Ptvsd 3.x-Legacydebugger ist der Standard in Visual Studio 2017, Version 15.7 und früher.

Je nach Visual Studio-Konfiguration müssen Sie möglicherweise ptvsd 3.x für das Remotedebugging verwenden:

• Visual Studio 2017, Version 15.7 und früher mit Python 2.6, 3.1 bis 3.4 oder IronPython
• Visual Studio 2019, Version 16.5 und höher mit Python 2.6, 3.1 bis 3.4 oder IronPython
• Frühe 4.x-Versionen

Wenn Ihre Konfiguration ein älteres Versionsszenario implementiert, zeigt Visual Studio den Fehler an, Debugger diese Python-Umgebungnicht unterstützt.

Einrichten des Remotedebuggings

Führen Sie die folgenden Schritte aus, um sich auf das Remotedebugging mit ptvsd 3.x vorzubereiten:

1. Richten Sie Ihren geheimen Schlüssel ein, der verwendet wird, um den Zugriff auf das ausgeführte Skript einzuschränken.

   In ptvsd 3.x erfordert die enable_attach-Funktion, dass Sie ein "Geheimnis" als erstes Argument übergeben.

   • Wenn Sie den Remotedebugger anfügen, geben Sie den geheimen Schlüssel mit dem Befehl enable_attach(secret="<secret>") ein.

   Obwohl Sie zulassen können, dass jeder über den Befehl enable_attach(secret=None) eine Verbindung herstellen kann, wird diese Option nicht empfohlen.

2. Erstellen Sie ihre Ziel-URL für die Verbindung im Formular tcp://<secret>@<ip_address>:5678.

   • tcp:// gibt den Verbindungstyp als TCP an.
   • <secret> ist die Zeichenfolge, die mit der funktion enable_attach im Python-Code übergeben wird.
   • <ip_address> ist die IP-Adresse des Remotecomputers, die eine explizite Adresse oder ein Name wie myvm.cloudapp.netsein kann.
   • :5678 ist die Portnummer des Remotedebuggings.

Sichere Verbindung mit TCPS-Protokoll

Standardmäßig wird die Verbindung mit dem Ptvsd 3.x-Remotedebugserver nur durch den geheimen Schlüssel gesichert, und alle Daten werden in Nur-Text übergeben. Für eine sicherere Verbindung unterstützt ptvsd 3.x SSL mithilfe des sicheren Formulars des TCP-Protokolls oder TCPS.

Führen Sie die folgenden Schritte aus, um ptvsd 3.x für die Arbeit mit dem TCPS-Protokoll zu konfigurieren:

1. Verwenden Sie auf dem Remotecomputer den Befehl openssl, um separate Dateien für den Schlüssel und das selbstsignierte Zertifikat zu generieren:

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

   • Geben Sie an der Eingabeaufforderung openssl den Hostnamen oder die IP-Adresse ein, die Sie verwenden, um eine Verbindung mit dem Common Nameherzustellen.

   Weitere Informationen finden Sie unter Selbstsigniertes Zertifikat in der Python ssl-Moduldokumentation. Beachten Sie, dass der in der Python-Dokumentation beschriebene Befehl nur eine einzige kombinierte Datei generiert.

2. Ändern Sie im Code den Aufruf der enable_attach-Funktion so, dass certfile und keyfile Argumente eingeschlossen werden, indem Sie die Dateinamen als Werte verwenden. Diese Argumente haben die gleiche Bedeutung wie für die Standardmäßige ssl.wrap_socket Python-Funktion.

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

   Sie können auch dieselbe Änderung in der Codedatei auf dem lokalen Computer vornehmen. Da dieser Code nicht tatsächlich ausgeführt wird, ist er nicht unbedingt erforderlich.

3. Starten Sie das Python-Programm auf dem Remotecomputer neu, damit es für das Debuggen bereit ist.

4. Sichern Sie den Kanal, indem Sie das Zertifikat der vertrauenswürdigen Stammzertifizierungsstelle auf dem Windows-Computer mit Visual Studio hinzufügen:

   1. Kopieren Sie die Zertifikatdatei vom Remotecomputer auf den lokalen Computer.

   2. Öffnen Sie Systemsteuerung, und wechseln Sie zu Windows Tools>Verwalten von Computerzertifikaten.

   3. Erweitern Sie im Dialogfeld certlm [Zertifikate - lokaler Computer] den Knoten Vertrauenswürdige Stammzertifizierungsstellen, klicken Sie mit der rechten Maustaste auf Zertifikate, und wählen Sie Alle Aufgaben>Importieren aus.

   4. Navigieren Sie zu der .cer Datei, die vom Remotecomputer kopiert wurde, und wählen Sie sie aus.

   5. Fahren Sie mit den Dialogfeldaufforderungen fort, um den Importvorgang abzuschließen.

5. Wiederholen Sie den Anfügevorgang in Visual Studio, wie weiter oben in Remoteanfügen über Python Toolsbeschrieben.

   Definieren Sie in diesem Fall tcps:// als das Protokoll für das Verbindungsziel (oder Qualifizierer).

   

Beheben von Verbindungsproblemen

Während des Verbindungsversuchs treten möglicherweise Probleme in Visual Studio auf. Überprüfen Sie die folgenden Szenarien, und ergreifen Sie bei Bedarf die entsprechenden Maßnahmen.

• Visual Studio warnt bei potenziellen Zertifikatproblemen beim Herstellen einer Verbindung über SSL.

  Aktion: Sie können die Nachricht ignorieren und fortfahren.

  Vorsicht

  Denken Sie daran, dass der Kanal zwar noch vor Lauschangriffen verschlüsselt ist, aber es kann offen für Man-in-the-Middle-Angriffe sein.

• In Visual Studio wird die Warnung angezeigt, dass das Remotezertifikat nicht vertrauenswürdig ist.

  Problem: Das Zertifikat wurde der vertrauenswürdigen Stammzertifizierungsstelle nicht ordnungsgemäß hinzugefügt.

  Aktion: Überprüfen Sie die Schritte, um das Zertifikat zur vertrauenswürdigen Stammzertifizierungsstelle auf dem Windows-Computer hinzuzufügen, und versuchen Sie die Verbindung erneut.

  

• Visual Studio zeigt die Warnung an, dass der Name des -Remotezertifikats nicht mit dem Hostnamen übereinstimmt.

  Problem: Der richtige Hostname oder die richtige IP-Adresse ist für den allgemeinen Namen für das Zertifikat nicht angegeben.

  Aktion: Überprüfen Sie erneut die Schritte in Sichern Sie die Verbindung mit TCPS. Achten Sie darauf, beim Erstellen des Zertifikats den richtigen Common Name zu verwenden, und versuchen Sie es erneut.

  

Verwandte Inhalte

• Remotedebuggen