Debuggen Ihres Python-Codes in Visual Studio

Visual Studio bietet eine umfassende Debuggingerfahrung für Python. In diesem Artikel erfahren Sie, wie Sie den Debugger an laufende Prozesse anhängen und Ausdrücke in den Fenstern Überwachen und Direkt auswerten. Im Debugger können Sie lokale Variablen überprüfen, Haltepunkte verwenden, Anweisungen in Einzelschritten, Prozedurschritten oder bis Rücksprung ausführen, die nächste Anweisung festlegen usw.

Szenariospezifische Debugging-Informationen finden Sie in den folgenden Artikeln:

• Linux-Remotedebuggen
• Python/C++ – Debuggen im gemischten Modus
• Symbole für das Debuggen im gemischten Modus

Voraussetzungen

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

• Python-Code für die Verwendung mit dem Debugger

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 Projektvorlage Aus vorhandenem Python-Code erstellen. Weitere Informationen finden Sie unter Create Project From Existing Code Files Wizard (Assistent für das Erstellen von Projekten aus vorhandenen Codedateien).

Sie benötigen jedoch keine Projekt- oder Projektmappendatei in Visual Studio, um Ihren Python-Code zu debuggen. Um Code in einer eigenständigen Python-Datei zu debuggen, öffnen Sie Ihre Datei in Visual Studio, und wählen Sie Debuggen>Debuggen starten aus. Visual Studio startet das Skript mit der globalen Standardumgebung und ohne Argumente. Sie haben dann volle Debugging-Unterstützung für Ihren Code. Weitere Informationen finden Sie unter Python-Umgebungen.

Grundlegendes Debuggen erkunden

Der grundlegende Debugging-Workflow umfasst das Festlegen von Haltepunkten, das schrittweise Durchlaufen des Codes, das Überprüfen von Werten und das Behandeln von Ausnahmen. Sie können eine Debugsitzung starten, indem Sie Debuggen>Debuggen starten auswählen oder die Tastenkombination F5 verwenden. Bei einem Projekt starten diese Aktionen die Startdatei mit der aktiven Umgebung des Projekts und allen für Projekteigenschaften angegebenen Befehlszeilenargumenten oder Suchpfaden. Informationen zum Konfigurieren der Eigenschaften finden Sie unter Projekt-Debuggingoptionen festlegen.

Festlegen der Projektstartdatei

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

• Um eine Projektdatei als Startdatei festzulegen, 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 Ausgabefenster geöffnet, in dem der Python-Interpreter ausgeführt wird, oder das Ausgabefenster wird kurz geöffnet und geschlossen.

Angeben der aktiven Umgebung

Wenn Sie eine Projektdatei verwenden, startet 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 Auswählen einer Python-Umgebung für ein Projekt.

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

Festlegen von Haltepunkten

Haltepunkte halten die Ausführung des Codes an einem markierten Punkt an, sodass Sie den Programmzustand überprüfen können.

Einige Haltepunkte in Python können für Entwickler überraschend sein, die mit anderen Programmiersprachen gearbeitet haben. In Python ist die gesamte Datei ausführbarer Code, daher führt Python die Datei beim Laden aus, um Klassen- oder Funktionsdefinitionen auf oberster Ebene zu verarbeiten. Wenn ein Haltepunkt festgelegt wurde, stellen Sie möglicherweise fest, dass der Debugger mitten in einer Klassendeklaration unterbricht. Dieses Verhalten ist korrekt, obwohl es manchmal überraschend ist.

• Um einen Haltepunkt festzulegen, klicken Sie auf den linken Rand des Code-Editors aus oder klicken Sie mit der rechten Maustaste auf eine Codezeile und wählen Sie Haltepunkt>Haltepunkt einfügen aus. In jeder Zeile mit einem 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>Haltepunkt löschen aus. Sie können einen Haltepunkt auch deaktivieren, indem Sie den roten Punkt und Haltepunkt>Haltepunkt deaktivieren auswählen.

  

Festlegen von Bedingungen und Aktionen

Sie können die Bedingungen anpassen, unter denen ein Haltepunkt ausgelöst wird, sodass z.B. nur dann unterbrochen wird, wenn eine Variable auf einen bestimmten Wert oder Wertebereich festgelegt ist.

• Klicken Sie zum Festlegen von Bedingungen 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 dieser Funktion in Visual Studio finden Sie unter Haltepunktbedingungen.

  

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

  

  Durch das Protokollieren einer Nachricht wird ein Ablaufverfolgungspunkt erstellt. Dadurch wird Ihrer Anwendung kein Protokollierungscode direkt hinzugefügt.

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

Schritt-für-Schritt-Ausführung des Codes

Wenn Visual Studio die Codeausführung an einem Haltepunkt stoppt, gibt es mehrere Befehle, mit denen Sie den Code durchlaufen oder Codeblöcke ausführen können, bevor sie erneut abgebrochen werden. Die Befehle sind an einigen Stellen in Visual Studio verfügbar, darunter auf der Debugger-Symbolleiste, im Menü Debuggen, im Kontextmenü im Code-Editor und über Tastenkombinationen.

Die folgende Tabelle fasst diese Befehle zusammen und stellt die Tastenkombination bereit:

Überprüfen und Ändern von Werten

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

• Um einen Wert mithilfe der Funktion DataTips beim Debuggen anzuzeigen, zeigen Sie mit dem Mauszeiger auf eine beliebige Variable im Editor. Sie können den Variablenwert auswählen, um ihn zu ändern:

  

• Um das Fenster Auto zu verwenden, wählen Sie Debuggen>Fenster>Auto aus. Dieses Fenster enthält Variablen und Ausdrücke, die der aktuellen Anweisung nahe kommen. Sie können auf die Wertspalte doppelklicken oder einen Wert auswählen und F2 drücken, um den Wert zu bearbeiten:

  

  Weitere Informationen zur Verwendung des Fensters Auto finden Sie unter Untersuchen von Variablen über die Fenster „Auto“ und „Lokal“.

• Um das Fenster Lokal zu verwenden, wählen Sie Debuggen>Fenster>Lokal aus. In diesem Fenster werden alle Variablen angezeigt, die sich im aktuellen Bereich befinden und erneut bearbeitet werden können:

  

  Weitere Informationen zur Verwendung des Fensters Lokal finden Sie unter Untersuchen von Variablen über die Fenster „Auto“ und „Lokal“.

• Um die Überwachungsfenster zu verwenden, wählen Sie Debuggen>Fenster>Überwachen>Überwachen 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 erneut ausgewertet:

  

  Weitere Informationen zur Verwendung des Überwachungsfensters finden Sie unter Festlegen einer Überwachung von Variablen in den Fenstern „Überwachung“ und „Schnellüberwachung“.

• Um einen Zeichenfolgenwert zu prüfen, wählen Sie Ansicht (Lupe) auf der rechten Seite des Eintrags Wert aus. Die Typen str, unicode, bytes und bytearray sind alle zur Überprüfung verfügbar.

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

  

  Nachdem Sie eine Visualisierung ausgewählt haben, zeigt ein Popup-Dialogfeld den nicht in Anführungszeichen gesetzten Zeichenfolgenwert entsprechend dem ausgewählten Typ an. Sie können die Zeichenfolge mit Umbruch und Bildlauf, Syntaxhervorhebung und Strukturansichten anzeigen. Diese Visualisierungen können beim Debuggen von Problemen mit langen und komplexen Zeichenfolgen helfen.

Anzeigen von Ausnahmen

Wenn während des Debuggens ein Fehler in Ihrem Programm auftritt, aber kein Ausnahmehandler dafür vorhanden ist, hält der Debugger am Punkt der Ausnahme an:

Wenn ein Fehler auftritt, können Sie den aktuellen Programmstatus einschließlich der Aufrufliste überprüfen. Wenn Sie jedoch den Code schrittweise durchgehen, löst der Debugging-Prozess die Ausnahme weiterhin aus, bis sie behandelt oder das Programm beendet wird.

• Um eine erweiterte Ansicht von Ausnahmen anzuzeigen, wählen Sie Debuggen>Fenster>Ausnahmeeinstellungen aus.

  

  Im Fenster Ausnahmeeinstellungen steuert das Kontrollkästchen neben einer Ausnahme, ob der Debugger immer unterbrochen wird, wenn diese Ausnahme ausgelöst wird.

• Um eine bestimmte Ausnahme häufiger zu unterbrechen, aktivieren Sie das Kontrollkästchen neben der Ausnahme im Fenster Ausnahmeeinstellungen.

• Standardmäßig werden die meisten Ausnahmen unterbrochen, wenn im Quellcode kein Ausnahmehandler gefunden werden kann. Um dieses Verhalten zu ändern, klicken Sie mit der rechten Maustaste auf eine Ausnahme, und passen Sie die Option Continue When Unhandled in User Code (Fortfahren, wenn in Benutzercode nicht behandelt) an. Um die Ausnahme seltener zu unterbrechen, deaktivieren Sie diese Option.

• Um eine Ausnahme zu konfigurieren, die im Fenster Ausnahmeeinstellungen nicht angezeigt wird, wählen Sie Hinzufügen (Plus-Symbol) aus. Geben Sie einen Namen für die zu überwachende Ausnahme ein. Der Name muss mit dem vollständigen Namen der Ausnahme übereinstimmen.

Konfigurieren von Projekt-Debuggingoptionen

Standardmäßig startet der Debugger Ihr Programm mit dem Python-Standardstartprogramm, ohne Befehlszeilenargumente und ohne andere spezielle Pfade oder Bedingungen. Sie können die Startoptionen für ein Python-Projekt konfigurieren, indem Sie die Debugging-Eigenschaften festlegen.

• Um auf die Debugging-Eigenschaften für ein Projekt zuzugreifen, klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Python-Projekt, wählen Sie Eigenschaften und dann die Registerkarte Debuggen aus.

  

In den folgenden Abschnitten werden die spezifischen Eigenschaften beschrieben.

Definieren des Startverhaltens

In der folgenden Tabelle sind mögliche 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 Eigenschaften beschrieben, die Sie festlegen können, um das Ausführungsverhalten des Debuggers zu konfigurieren.

Arbeiten mit interaktiven Fenstern

Es gibt zwei interaktive Fenster, die Sie während einer Debugsitzung verwenden können: das standardmäßige Visual Studio-Direktfenster und das interaktive Python-Debugfenster.

Öffnen des Direktfensters

Sie können das standardmäßige Visual Studio-Direktfenster verwenden, um Python-Ausdrücke schnell auszuwerten und Variablen in Ihrem ausgeführten Programm zu überprüfen oder zuzuweisen. Weitere Informationen finden Sie unter Direktfenster.

• Um das Direktfenster zu öffnen, wählen Sie Debuggen>Fenster>Direkt aus. Sie können auch die Tastenkombination STRG+Alt+I verwenden.

Öffnen des Fensters zum interaktiven Debuggen

Das interaktive Python-Debugfenster bietet eine umfangreiche Umgebung mit der vollständigen Erfahrung Interaktive REPL, die beim Debuggen verfügbar ist, einschließlich des Schreibens und Ausführens von Code. Dieses Fenster stellt automatisch eine Verbindung zu jedem Prozess her, der mit dem Python-Standardstartprogramm gestartet wird (einschließlich Prozessen, die über Debuggen>An den Prozess anhängen angefügt werden). Dieses Fenster ist jedoch nicht verfügbar, wenn Sie das C/C++-Debugging im gemischten Modus verwenden.

• Um das Fenster zum interaktiven Debuggen zu verwenden, wählen Sie Debuggen>Fenster>Interaktives Python-Debuggen (Umschalt+Alt+I) aus.

  

Das Fenster zum interaktiven Debuggen unterstützt zusätzlich zu den REPL-Standardbefehlen spezielle Metabefehle, wie in der folgenden Tabelle beschrieben:

Standardmäßige Debuggerfenster wie Prozesse, Threads und Aufrufliste werden nicht mit dem Fenster zum interaktiven Debuggen synchronisiert. Wenn Sie den aktiven Prozess, Thread oder Frame im Fenster zum interaktiven Debuggen ändern, sind die anderen Debugger-Fenster nicht betroffen. Entsprechend gilt: Das Ändern des aktiven Prozesses, Threads oder Frames in anderen Debuggerfenstern wirkt sich nicht auf das Fenster zum interaktiven Debuggen aus.

Verwenden des Legacydebuggers

Abhängig von Ihrer Umgebungskonfiguration müssen Sie möglicherweise den Legacy-Debugger 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 Legacy-Debugger ist der Standard in Visual Studio 2017 Version 15.7 und früher.

• Um den Legacydebugger zu verwenden, wählen Sie Extras>Optionen, erweitern Sie die Optionen Python>Debugging, und wählen Sie die Option Legacydebugger verwenden aus.

Support für ältere Visual Studio- oder Python-Versionen

Visual Studio 2017, Version 15.8 und höher, verwendet einen Debugger, der auf ptvsd-Version 4.1 und höher basiert. Visual Studio 2019 verwendet ab Version 16.5 einen Debugger, der auf debugpy basiert. 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 die Fehlermeldung Diese Python-Umgebung wird vom Debugger nicht unterstützt an:

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

Unterstützt ältere ptvsd-Versionen

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

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

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 Ihrer ptvsd-Installation

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

1. Navigieren Sie im Fenster Python-Umgebungen zur Registerkarte Pakete.

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), klicken Sie rechts im Paket auf X, um die ältere Version zu deinstallieren. Visual Studio verwendet dann die gebündelte Version. (Sie können die Deinstallation auch über PowerShell mithilfe des pip uninstall ptvsd-Befehls durchführen.

4. Alternativ können Sie das ptvsd-Paket auf die neueste Version aktualisieren, indem Sie die Anweisungen im Abschnitt Problembehandlung für Debug-Szenarien befolgen.

Problembehandlung für Debug-Szenarien

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

Aktualisieren von ptvsd für Visual Studio 2019

Wenn Sie Probleme mit dem Debugger in Visual Studio 2019 Version 16.4 und früher haben, aktualisieren Sie zunächst Ihre Version des Debuggers wie folgt:

1. Navigieren Sie im Fenster Python-Umgebungen zur Registerkarte Pakete.

2. Geben Sie ptvsd --upgrade in das Suchfeld ein, wählen Sie dann Run command: pip install ptvsd --upgrade aus. (Sie können denselben Befehl auch in PowerShell verwenden.)

   

   Wenn die Probleme weiterhin auftreten, melden Sie ein Problem im PTVS GitHub-Repository.

   Hinweis

   Für Visual Studio 2019 ab Version 16.5 ist debugpy Teil der Python-Workload von Visual Studio und wird zusammen mit Visual Studio aktualisiert.

Aktivieren der Debuggerprotokollierung

Im Rahmen der Untersuchung eines Debuggerproblems kann Microsoft Sie bitten, Debuggerprotokolle zu aktivieren und zu erfassen, die bei der Diagnose helfen.

Die folgenden Schritte ermöglichen das Debuggen in der aktuellen Visual Studio-Sitzung:

1. Öffnen Sie hierzu in Visual Studio ein Befehlsfenster, indem Sie Ansicht>Weitere Fenster>Befehlsfenster auswählen.

2. Geben Sie den folgenden Befehl ein:

   DebugAdapterHost.Logging /On /OutputWindow
   

3. Beginnen Sie mit dem Debuggen, und führen Sie alle notwendigen Schritte aus, um Ihr Problem zu reproduzieren. Während dieser Zeit werden Debugprotokolle im Fenster Ausgabe unter Adapterhostprotokoll debuggen angezeigt. Sie können die Protokolle dann aus diesem Fenster kopieren und in ein GitHub-Problem, eine E-Mail usw. einfügen.

   

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

   DebugAdapterHost.Logging /On
   

5. Beginnen Sie mit dem Debuggen, und reproduzieren Sie Ihr Problem erneut. Die Debuggerprotokolle befinden sich in %temp%\DebugAdapterHostLog.txt.

Zugehöriger Inhalt

• Debuggen in Visual Studio
• Python/C++ – Debuggen im gemischten Modus
• Symbole für das Debuggen im gemischten Modus