Debuggen des Python Codes in Visual Studio

Visual Studio bietet eine umfassende Debugerfahrung für Python. In diesem Artikel erfahren Sie, wie Sie den Debugger an ausgeführte Prozesse anfügen und Ausdrücke in den Fenstern Überwachung und Direkt auswerten. Im Debugger können Sie lokale Variablen überprüfen, Haltepunkte verwenden, Anweisungen in/out/over, Set Next Statement usw. verwenden.

Szenariospezifische Debuginformationen finden Sie in den folgenden Artikeln:

• Linux-Remotedebugging
• Mixed-Mode Python/C++-Debugging
• Symbole für das Debuggen im gemischten Modus

Voraussetzungen

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

• Python Code, der mit dem Debugger verwendet werden soll.

Debuggen von Code mit oder ohne Projekt

Wenn Sie Ihre Python Umgebung und Argumente steuern möchten, erstellen Sie zuerst ein Projekt für Ihren Code. Sie können ein Projekt mit der Von vorhandenem Python-Code Projekt-Vorlage erstellen. Weitere Informationen finden Sie unter Create a project from existing Python code files.

Sie benötigen jedoch keine Projekt- oder Lösungsdatei in Visual Studio, um Ihren Python Code zu debuggen. Um Code in einer eigenständigen Python Datei zu debuggen, öffnen Sie die Datei in Visual Studio, und wählen Sie Debug>Start Debugging aus. Visual Studio startet das Skript mit der globalen Standardumgebung und ohne Argumente. Anschließend verfügen Sie über vollständige Debuggingunterstützung für Ihren Code. Weitere Informationen finden Sie unter Python umgebungen.

Grundlegendes Debuggen erkunden

Der grundlegende Debug-Workflow umfasst das Setzen von Haltepunkten, das Schritt-für-Schritt-Durchlaufen des Codes, die Überprüfung von Werten und die Ausnahmebehandlung. Sie können eine Debugsitzung starten, indem Sie "Debuggen>starten" auswählen oder die F5-Tastenkombination verwenden. Bei einem project starten diese Aktionen die datei startup mit der aktiven Umgebung des project und allen Befehlszeilenargumenten oder Suchpfaden, die für Project Properties angegeben sind. Informationen zum Konfigurieren der Eigenschaften finden Sie unter Festlegen von Projektdebuggingoptionen.

Festlegen der Projektstartdatei

Die Startdatei für ein Projekt wird fett in Projektmappen-Explorer angezeigt. Sie können auswählen, welche Datei als Startdatei verwendet werden soll.

• Wenn Sie eine Projektdatei als Startdatei angeben möchten, klicken Sie mit der rechten Maustaste auf die Datei, und wählen Sie "Als Startelement festlegen" aus.

In Visual Studio 2017, Version 15.6 und höher, wird eine Warnung angezeigt, wenn Sie keinen angegebenen Startdateisatz haben. In früheren Versionen von Visual Studio wird möglicherweise ein OutputFenster geöffnet, in dem der Python-Dolmetscher ausgeführt wird, oder das fenster Output wird kurz geöffnet und geschlossen.

Angeben der aktiven Umgebung

Wenn Sie eine Projektdatei verwenden, beginnt der Debugger immer mit der aktiven Python Umgebung für das Projekt. Sie können die aktuelle aktive Umgebung ändern. Weitere Informationen finden Sie unter Select a Python environment for a project.

Wenn Sie eine eigenständige Python Codedatei debuggen, startet Visual Studio das Skript mit der globalen Standardumgebung und ohne Argumente.

Festlegen von Haltepunkten

Haltepunkte beenden die Ausführung von Code an einem markierten Punkt, damit Sie den Programmzustand überprüfen können.

Einige Haltepunkte in Python können für Entwickler, die mit anderen Programmiersprachen gearbeitet haben, überraschend sein. In Python ist die gesamte Datei ausführbarer Code, sodass Python die Datei ausführt, wenn sie geladen wird, um Klassen- oder Funktionsdefinitionen der obersten Ebene zu verarbeiten. Wenn ein Haltepunkt festgelegt ist, kann es sein, dass der Debugger mitten in einer Klassendeklaration unterbricht. Dieses Verhalten ist richtig, auch wenn es manchmal überraschend ist.

• Um einen Haltepunkt festzulegen, wählen Sie im linken Rand des Code-Editors aus, oder klicken Sie mit der rechten Maustaste auf eine Codezeile, und wählen Sie "Haltepunkt>einfügen" aus. In jeder Zeile mit einem festgelegten Haltepunkt wird ein roter Punkt angezeigt.

  

  

• Um einen Haltepunkt zu entfernen, wählen Sie den roten Punkt aus, oder klicken Sie mit der rechten Maustaste auf die Codezeile, und wählen Sie "Haltepunkt>löschen" aus. Sie können einen Haltepunkt auch deaktivieren, indem Sie den roten Punkt auswählen und den Haltepunkt "Haltepunkt>deaktivieren" auswählen.

  Das Screenshot zeigt, wie ein Haltepunkt im linken Rand der Codedatei in Visual Studio deaktiviert wird.

Festlegen von Bedingungen und Aktionen

Sie können die Bedingungen anpassen, unter denen ein Haltepunkt ausgelöst wird, indem sie nur dann unterbrochen werden, wenn eine Variable auf einen bestimmten Wert oder Wertbereich gesetzt ist.

• Wenn Sie Bedingungen festlegen möchten, klicken Sie mit der rechten Maustaste auf den roten Punkt des Haltepunkts, und wählen Sie "Bedingungen" aus. Das Dialogfeld "Haltepunkteinstellungen" wird geöffnet.

  Im Dialogfeld können Sie mehrere Bedingungen hinzufügen und bedingte Ausdrücke mithilfe von Python Code erstellen. Ausführliche Informationen zu diesem Feature in Visual Studio finden Sie unter Breakpoint-Bedingungen.

  

  Screenshot, der zeigt, wie Sie die Option zum Konfigurieren von Bedingungen für einen Haltepunkt in Visual Studio auswählen.

• Sie haben auch die Optionen zum Festlegen von Aktionen für einen Haltepunkt. Sie können eine Meldung zum Protokollieren im Ausgabefenster erstellen und optional angeben, dass die Ausführung automatisch fortgesetzt werden soll.

  Screenshot, der zeigt, wie Ablaufverfolgungsaktionen für einen Haltepunkt in Visual Studio erstellt werden können.

  

  Durch das Protokollieren einer Nachricht wird ein Ablaufverfolgungspunkt erstellt, der Ihrer Anwendung keinen Protokollierungscode direkt hinzu fügt.

Je nachdem, wie Sie Bedingungen und Aktionen für einen Haltepunkt konfigurieren, ändert sich das rote Symbol am linken Rand, um Ihre Einstellungen anzugeben. Möglicherweise wird die Punktform, ein Uhr-Timer oder eine Raute angezeigt.

Schrittweise durch den Code gehen

Wenn Visual Studio die Codeausführung an einem Haltepunkt stoppt, gibt es mehrere Befehle, mit denen Sie den Code schrittweise durchgehen oder Codeblöcke ausführen können, bevor die Ausführung erneut unterbrochen wird. Die Befehle sind an einigen Stellen in Visual Studio verfügbar, einschließlich der Symbolleiste Debugger-, dem Menü Debuggen, dem Kontextmenü im Code-Editor und über Tastenkombinationen.

In der folgenden Tabelle werden diese Befehle zusammengefasst und die Tastenkombination bereitgestellt:

Überprüfen und Ändern von Werten

Wenn Sie die Codeausführung im Debugger beenden, können Sie die Werte von Variablen überprüfen und ändern. Sie können auch das Überwachungsfenster verwenden, um einzelne Variablen und benutzerdefinierte Ausdrücke zu überwachen. Weitere Informationen finden Sie unter Überprüfen von Variablen.

• Um einen Wert mithilfe der DataTips-Funktion während des Debuggens anzuzeigen, zeigen Sie mit der Maus auf eine beliebige Variable im Editor. Sie können den Variablenwert auswählen, um ihn zu ändern:

  

  

• Wenn Sie das Fenster Locals verwenden möchten, wählen Sie Debug>Windows>Locals aus. In diesem Fenster werden alle Variablen angezeigt, die sich im aktuellen Bereich befinden. Sie können in der Wertspalte doppelklicken oder F2 auswählen und eingeben, um den Wert zu bearbeiten:

  

  

  Weitere Informationen zur Verwendung des Fensters "Lokal" finden Sie unter "Überprüfen von Variablen" in den Fenstern "Autos" und "Locals".

• Um die Watch-Fenster zu verwenden, wählen Sie Debug>Windows>Watch>Watch 1-4 aus. Mit dieser Option können Sie beliebige Python Ausdrücke eingeben und die Ergebnisse anzeigen. Ausdrücke werden für jeden Schritt neu ausgewertet:

  

  Screenshot, der das Überwachungsfenster im Visual Studio-Debugger anzeigt.

  Weitere Informationen zur Verwendung des Überwachungsfensters finden Sie unter Festlegen einer Überwachung auf Variablen mit den Fenstern "Watch" und "QuickWatch".

• Um einen Zeichenfolgenwert zu prüfen, wählen Sie auf der rechten Seite des Werteintragsdie Option Ansicht (Lupe) aus. Die str, unicode, bytesund bytearray Typen sind alle zur Inspektion verfügbar.

  Im Dropdownmenü "Ansicht " werden vier Visualisierungsoptionen angezeigt: Text, HTML, XML oder JSON.

  Screenshot, das zeigt, wie Sie über das Vergrößerungsglas im Visual Studio-Debugger auf Visualisierungen zugreifen.

  

  Nachdem Sie eine Visualisierung ausgewählt haben, zeigt ein Popup-Dialog den nicht zitierten Zeichenfolgewert entsprechend dem ausgewählten Typ an. Sie können den Text mit Zeilenumbruch und Bildlauf, Syntaxhervorhebung und Strukturansichten anzeigen. Diese Visualisierungen können beim Debuggen von Problemen mit langen und komplexen Zeichenfolgen helfen.

Ausnahmen anzeigen

Wenn während des Debuggens ein Fehler in Ihrem Programm auftritt, jedoch kein Ausnahmehandler dafür vorhanden ist, wird der Debugger an der Stelle der Ausnahme unterbrochen:

Wenn ein Fehler auftritt, können Sie den aktuellen Programmstatus einschließlich des Aufrufstapels überprüfen. Wenn Sie den Code jedoch schrittweise durchlaufen, löst der Debuggingprozess die Ausnahme weiterhin aus, bis es behandelt wird oder das Programm beendet wird.

• Um eine erweiterte Ansicht der Ausnahmen anzuzeigen, wählen Sie Debug>Windows>Ausnahmeeinstellungen aus.

  

  

  Im Fenster Ausnahmeneinstellungen steuert das Kontrollkästchen neben einer Ausnahme, ob der Debugger beim Auslösen dieser Ausnahme immer anhält.

• Wenn Sie für eine bestimmte Ausnahme häufiger aufbrechen möchten, aktivieren Sie das Kontrollkästchen neben der Ausnahme im Fenster "Ausnahmeeinstellungen" .

• Standardmäßig werden die meisten Ausnahmen unterbrochen, wenn ein Ausnahmehandler im Quellcode nicht gefunden werden kann. Wenn Sie dieses Verhalten ändern möchten, klicken Sie mit der rechten Maustaste auf eine Ausnahme und ändern Sie die Option Weiter bei unbehandeltem Benutzercode. Deaktivieren Sie diese Option, um für die Ausnahme weniger häufig zu unterbrechen.

• Wenn Sie eine Ausnahme konfigurieren möchten, die nicht im Fenster "Ausnahmeeinstellungen " angezeigt wird, wählen Sie "Hinzufügen" (Pluszeichen) aus. Geben Sie einen Namen für die Ausnahme ein, die überwacht werden soll. Der Name muss mit dem vollständigen Namen der Ausnahme übereinstimmen.

Konfigurieren von Projektdebuggingoptionen

Standardmäßig startet der Debugger ihr Programm mit dem Standardmäßigen Python Startprogramm, keine Befehlszeilenargumente und keine anderen speziellen Pfade oder Bedingungen. Sie können die Startoptionen für ein Python Projekt konfigurieren, indem Sie die Debugeigenschaften festlegen.

• Wenn Sie auf die Debugeigenschaften eines Projekts zugreifen möchten, klicken Sie mit der rechten Maustaste auf Ihr Python-Projekt im Projektmappen-Explorer, wählen Sie Properties aus, und wählen Sie dann die Registerkarte Debug aus.

  

  

In den folgenden Abschnitten werden die spezifischen Eigenschaften beschrieben.

Definieren des Startverhaltens

In der folgenden Tabelle sind die möglichen Werte für die Eigenschaft "Startmodus " aufgeführt. Verwenden Sie diese Eigenschaft, um das Startverhalten für den Debugger zu definieren.

Definieren des Ausführungsverhaltens

In der folgenden Tabelle werden die Eigenschaften beschrieben, die Sie festlegen können, um das Ausführungsverhalten für den Debugger zu konfigurieren.

Arbeiten mit interaktiven Fenstern

Es gibt zwei interactive Fenster, die Sie während einer Debugsitzung verwenden können: das Standardfenster Visual Studio Immediate und das Fenster Python Debug Interactive.

Öffnen des Direktfensters

Sie können das Standardfenster Visual Studio Immediate verwenden, um schnell Python Ausdrücke auszuwerten und Variablen in Ihrem ausgeführten Programm zu überprüfen oder zuzuweisen. Weitere Informationen finden Sie im Direktfenster.

• Um das Fenster Immediate zu öffnen, wählen Sie Debug>Windows>Immediate aus. Sie können auch die Tastenkombination STRG+ALT+I verwenden.

Öffnen des interaktiven Debugfensters

Das Fenster Python Debug Interactive bietet eine umfassende Umgebung mit dem vollständigen Interactive REPL während des Debuggens, einschließlich Schreiben und Ausführen von Code. Dieses Fenster stellt automatisch eine Verbindung zu jedem im Debugger gestarteten Prozess her, indem es den Standard-Python-Launcher verwendet, einschließlich der Prozesse, die über Debug>Attach to Process angehängt sind. Dieses Fenster ist jedoch bei Verwendung des C/C++-Debuggings im gemischten Modus nicht verfügbar.

• So verwenden Sie das Fenster Debug Interactive, wählen Sie Debug>Windows>Python Debug Interactive (Shift+Alt+I) aus.

  

  

Das Fenster "Interaktives Debuggen " unterstützt zusätzlich zu den standardmäßigen REPL-Befehlen spezielle Metabefehle, wie in der folgenden Tabelle beschrieben:

Die Standarddebuggerfenster wie Prozesse, Threads und Aufrufstapel werden nicht mit dem Fenster " Interaktives Debuggen " synchronisiert. Wenn Sie den aktiven Prozess, den Thread oder den Frame im Fenster "Interaktives Debuggen " ändern, sind die anderen Debuggerfenster nicht betroffen. Ebenso wirkt sich das Ändern des aktiven Prozesses, threads oder Frames in den anderen Debuggerfenstern nicht auf das Fenster "Interaktives Debuggen " aus.

Verwenden Sie den Legacy-Debugger

Je nach Ihrer Umgebungskonfiguration müssen Sie möglicherweise den Legacydebugger 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
• ptvsd 3.x und frühe 4.x-Versionen

Der Legacydebugger ist die Standardeinstellung in Visual Studio 2017, Version 15.7 und früher.

• Um den Legacydebugger zu verwenden, wählen Sie Tools>Options aus, erweitern Sie die Optionen Python>Debugging, und wählen Sie die Option Use legacy debugger aus.

Unterstützen älterer Visual Studio oder Python Versionen

Visual Studio 2017, Version 15.8 und höher, verwenden Sie einen Debugger basierend auf ptvsd Version 4.1 und höher. Visual Studio 2019, Version 16.5 und höher, verwenden Sie einen Debugger basierend auf debugpy. Diese beiden Versionen des Debuggers sind mit Python 2.7 oder Python 3.5 und höher kompatibel.

Wenn Sie eine dieser Versionen von Visual Studio ausführen, aber Python 2.6, 3.1 bis 3.4 oder IronPython verwenden, zeigt Visual Studio den Fehler an, dass der Debugger diese Python-Umgebung nicht unterstützt:

Wenn Visual Studio diesen Umgebungsfehler meldet, müssen Sie den Legacydebugger verwenden.

Unterstützung älterer ptvsd-Versionen

Wenn Sie eine ältere Version von ptvsd in der aktuellen Umgebung verwenden (z. B. eine frühere Version von 4.0.x oder eine 3.x-Version, die für das Remotedebugging erforderlich ist), Visual Studio möglicherweise einen Fehler oder eine Warnung anzeigen.

Wenn Ihre Umgebung ptvsd 3.x verwendet, zeigt Visual Studio den Fehler an, Debugger-Paket konnte nicht geladen werden:

Die Warnung, Debuggerpaket ist veraltet, wird angezeigt, wenn Sie eine frühere 4.x-Version von ptvsd verwenden:

Wenn Visual Studio diese Umgebungsfehler meldet, müssen Sie den Legacydebugger verwenden.

Verwalten Der Ptvsd-Installation

Führen Sie die folgenden Schritte aus, um Ihre Ptvsd-Installation zu verwalten:

1. Wechseln Sie im Fenster Python Umgebungen zur Registerkarte Packages.

2. Geben Sie ptvsd in das Suchfeld ein, und überprüfen Sie die installierte Version von ptvsd:

   

   

3. Wenn die Version niedriger als 4.1.1a9 ist (die mit Visual Studio gebündelte Version), wählen Sie die X rechts neben dem Paket aus, um die ältere Version zu deinstallieren. Visual Studio verwendet dann die gebündelte Version. (Sie können auch mithilfe des pip uninstall ptvsd Befehls über PowerShell deinstallieren.)

4. Alternativ können Sie das ptvsd-Paket auf die neueste Version aktualisieren, indem Sie die Anweisungen im Abschnitt "Problembehandlungsszenarien " befolgen.

Problembehandlung bei Debugszenarien

In den folgenden Szenarien werden weitere Problembehandlungsoptionen für die Debugkonfiguration beschrieben.

Aktualisierung von ptvsd für Visual Studio 2019

Wenn Sie Probleme mit dem Debugger in Visual Studio 2019, Version 16.4 und früher haben, führen Sie zuerst ein Upgrade ihrer Version des Debuggers wie folgt aus:

1. Wechseln Sie im Fenster Python Umgebungen zur Registerkarte Packages.

2. Geben Sie "ptvsd --upgrade " in das Suchfeld ein, und wählen Sie dann den Befehl "Ausführen" aus: pip install ptvsd --upgrade. (Sie können auch denselben Befehl aus PowerShell verwenden.)

   

   Wenn Probleme weiterhin bestehen, geben Sie ein Problem auf dem PTVS GitHub Repository an.

   Hinweis

   Für Visual Studio 2019, Version 16.5 und höher, ist debugpy Teil der Visual Studio Python Workload und wird zusammen mit Visual Studio aktualisiert.

Debuggerprotokollierung aktivieren

Im Verlauf der Untersuchung eines Debuggerproblems bitten Microsoft Sie möglicherweise, Debuggerprotokolle zu aktivieren und zu sammeln, um bei der Diagnose zu helfen.

Die folgenden Schritte aktivieren das Debuggen in der aktuellen Visual Studio Sitzung:

1. Öffnen Sie ein Befehlsfenster in Visual Studio, indem Sie View>Other Windows>Command Window auswählen.

2. Geben Sie den folgenden Befehl ein:

   DebugAdapterHost.Logging /On /OutputWindow
   

3. Starten Sie das Debuggen, und durchlaufen Sie die Schritte, die erforderlich sind, um Ihr Problem zu reproduzieren. Während dieser Zeit werden Debugprotokolle im Ausgabefenster unter Debugadapter-Hostprotokoll angezeigt. Anschließend können Sie die Protokolle aus diesem Fenster kopieren und in ein GitHub Problem, E-Mail usw. einfügen.

   

   

4. Wenn Visual Studio nicht mehr reagiert oder Sie andernfalls nicht mehr auf die Output Fenster zugreifen können, starten Sie Visual Studio neu, öffnen Sie ein Befehlsfenster, und geben Sie den folgenden Befehl ein:

   DebugAdapterHost.Logging /On
   

5. Starten Sie das Debuggen, und reproduzieren Sie das Problem erneut. Die Debuggerprotokolle befinden sich in %temp%\DebugAdapterHostLog.txt.

Verwandte Inhalte

• Debugging in Visual Studio
• Mixed-Mode Python/C++-Debugging
• Symbole für das Debuggen im gemischten Modus