Debugging

Sie können C#-Anwendungen in Visual Studio Code mit der Microsoft C#-Erweiterung debuggen.

Ausführen und Debuggen

Die C#-Erweiterung bietet zusammen mit dem C# Dev Kit mehrere Möglichkeiten, Ihre C#-Anwendung auszuführen und zu debuggen.

Um ohne das C# Dev Kit auszuführen und zu debuggen, finden Sie in der Dokumentation auf der GitHub-Seite der Microsoft C#-Erweiterung weitere Informationen.

Debuggen mit F5

Wenn die C# Dev Kit-Erweiterung installiert ist und keine Debugkonfigurationen in der Debugansicht zur Auswahl stehen, können Sie das Debuggen Ihres Projekts starten, indem Sie eine .cs-Datei öffnen und dann F5 drücken. Der Debugger findet Ihr Projekt automatisch und beginnt mit dem Debuggen. Falls Sie mehrere Projekte haben, werden Sie aufgefordert, das zu debuggende Projekt auszuwählen.

Sie können eine Debugsitzung auch über die Ansicht Ausführen und Debuggen in der Seitenleiste von VS Code starten. Mehr dazu unter Debuggen in VS Code.

Debuggen mit dem Projektmappen-Explorer

Wenn die C# Dev Kit-Erweiterung installiert ist, finden Sie ein Debuggen-Kontextmenü, wenn Sie im Projektmappen-Explorer mit der rechten Maustaste auf Ihr Projekt klicken.

Es gibt drei Optionen:

• Neue Instanz starten - Startet Ihr Projekt mit angehängtem Debugger.
• Ohne Debuggen starten - Führt Ihr Projekt ohne angehängten Debugger aus.
• In neue Instanz einsteigen (Step into) - Startet Ihr Projekt mit angehängtem Debugger, hält jedoch am Einstiegspunkt Ihres Codes an.

Debuggen mit der Befehlspalette

Wenn die C# Dev Kit-Erweiterung installiert ist, können Sie das Debuggen auch über die Befehlspalette ⇧⌘P (Windows, Linux Ctrl+Shift+P) mit dem Befehl Debuggen: Auswählen und Debuggen starten initiieren.

Hinweis: Dies fügt Ihrer Debug-Dropdownliste einen Startkonfigurationseintrag hinzu.

Debuggen mit dynamischen (im Arbeitsspeicher befindlichen) Startkonfigurationen

Wenn das C# Dev Kit installiert ist, können Sie dynamische Startkonfigurationen erstellen. Wie Sie diese erstellen, hängt davon ab, ob Ihr Projekt bereits eine launch.json-Datei enthält.

Existierende launch.json

Wenn Sie eine bestehende launch.json haben, können Sie zur Debugansicht gehen, das Dropdownmenü öffnen und die Option C# wählen. Sie erhalten eine Auswahl an Startzielen, die Sie Ihrer Dropdownliste hinzufügen können. Nach der Auswahl können Sie F5 drücken oder über Debuggen starten die neu generierte Konfiguration verwenden.

Keine launch.json

Wenn Ihr Projekt keine launch.json enthält, können Sie diese dynamischen Konfigurationen über die Option Alle automatischen Debugkonfigurationen anzeigen in der Debugansicht hinzufügen und darauf zugreifen.

Entfernen von dynamischen (im Arbeitsspeicher befindlichen) Startkonfigurationen

Sie können die generierten Konfigurationen über die Befehlspalette ⇧⌘P (Windows, Linux Ctrl+Shift+P) und den Befehl Debuggen: Auswählen und Debuggen starten entfernen.

Im Dropdownmenü werden alle vorhandenen Debugkonfigurationen aufgelistet. Wenn Sie mit der Maus über die dynamischen Konfigurationen fahren, erscheint rechts ein anklickbares Papierkorb-Symbol. Sie können dieses Symbol auswählen, um die dynamische Konfiguration zu entfernen.

Debuggen mit Editor-Schaltflächen für Debuggen/Ausführen

Wenn eine .cs-Datei im Editor geöffnet ist, sind die Optionen zum Ausführen und Debuggen über die Schaltflächen in der oberen rechten Ecke des Editor-Fensters zugänglich. Diese Aktionen verwenden die aktuelle Datei, um das Projektsystem abzufragen und das zugehörige Projekt für den Start zu ermitteln.

Die zwei Optionen sind:

• Projekt, das mit dieser Datei verknüpft ist, ausführen: Startet Ihr Programm mit noDebug: true über den Debug-Adapter.
• Projekt, das mit dieser Datei verknüpft ist, debuggen: Startet Ihr Programm unter dem Debugger.

Debuggen mit launch.json

Wenn Sie das C# Dev Kit verwenden, empfehlen wir, diese Option nicht zu nutzen. Falls Sie die Debugkonfiguration jedoch direkt anpassen müssen, lesen Sie Konfigurieren von launch.json für das C#-Debuggen.

An einen Prozess anhängen

Sie können einen C#-Prozess über die Befehlspalette ⇧⌘P (Windows, Linux Ctrl+Shift+P) und den Befehl Debuggen: An einen .NET 5+ oder .NET Core-Prozess anhängen an einen Prozess anhängen.

Konfigurationsoptionen

Es gibt viele Optionen und Einstellungen zur Konfiguration des Debuggers. Sie können launchSettings.json, VS Code Benutzereinstellungen oder die direkte Bearbeitung Ihrer launch.json verwenden, um Debugoptionen zu ändern.

launchSettings.json

Wenn Sie eine launchSettings.json aus Visual Studio haben, sollten Ihre Profile unter Ausführen mit F5 oder Ausführen mit Befehlspalette aufgelistet sein.

Weitere Details finden Sie unter Konfigurieren des C#-Debuggens.

Benutzereinstellungen

Wenn Sie während der Verwendung des C#-Debuggers Einstellungen ändern möchten, finden Sie diese Optionen unter Datei > Einstellungen > Einstellungen (⌘, (Windows, Linux Ctrl+,)).

• csharp.debug.stopAtEntry - Wenn true, hält der Debugger am Einstiegspunkt des Ziels an. Standardwert ist false.
• csharp.debug.console - Gibt bei Konsolenprojekten an, in welcher Konsole das Zielprogramm gestartet werden soll. Hinweis: Diese Option wird nur für den Debugkonfigurationstyp 'dotnet' verwendet.
  • internalConsole [Standard] - Die Debug-Konsole von VS Code. Dieser Modus ermöglicht es, Nachrichten sowohl vom Debugger als auch vom Zielprogramm an einem Ort zu sehen. Weitere Informationen finden Sie in der vollständigen Dokumentation.
  • integratedTerminal - Das integrierte Terminal von VS Code.
  • externalTerminal - Externes Terminal, das über Benutzereinstellungen konfiguriert werden kann.
• csharp.debug.sourceFileMap - Ordnet Build-Zeit-Pfade lokalen Quellpfaden zu. Alle Instanzen des Build-Zeit-Pfads werden durch den lokalen Quellpfad ersetzt.
    Beispiel
      {\"<build-path>\":\"<local-source-path>\"}
• csharp.debug.justMyCode - Wenn aktiviert (Standard), zeigt der Debugger nur Benutzercode ("Mein Code") an und steigt nur in diesen ein, während Systemcode und anderer optimierter Code oder Code ohne Debugsymbole ignoriert wird. Mehr Informationen.
• csharp.debug.requireExactSource - Flag, das erzwingt, dass der aktuelle Quellcode mit der PDB übereinstimmt. Standardwert ist true.
• csharp.debug.enableStepFiltering - Flag zur Aktivierung des Überspringens (Step-Over) von Eigenschaften und Operatoren. Standardwert ist true.
• csharp.debug.logging.exceptions - Flag zur Bestimmung, ob Ausnahmenachrichten im Ausgabefenster protokolliert werden sollen. Standardwert ist true.
• csharp.debug.logging.moduleLoad - Flag zur Bestimmung, ob Modulladeereignisse im Ausgabefenster protokolliert werden sollen. Standardwert ist true.
• csharp.debug.logging.programOutput - Flag zur Bestimmung, ob die Programmausgabe im Ausgabefenster protokolliert werden soll, wenn keine externe Konsole verwendet wird. Standardwert ist true.
• csharp.debug.logging.diagnosticsLog - Verschiedene Einstellungen zur Diagnose von Debugger-Problemen.
• csharp.debug.logging.browserStdOut - Flag zur Bestimmung, ob stdout-Text vom Starten des Webbrowsers im Ausgabefenster protokolliert werden soll. Standardwert ist true.
• csharp.debug.logging.elapsedTiming - Wenn true, enthält das Engine-Protokoll adapterElapsedTime- und engineElapsedTime-Eigenschaften, die die Zeitdauer einer Anfrage in Mikrosekunden angeben. Standardwert ist false.
• csharp.debug.logging.threadExit - Steuert, ob eine Nachricht protokolliert wird, wenn ein Thread im Zielprozess beendet wird. Standardwert ist false.
• csharp.debug.logging.processExit - Steuert, ob eine Nachricht protokolliert wird, wenn der Zielprozess beendet wird oder das Debuggen gestoppt wird. Standardwert ist true.
• csharp.debug.suppressJITOptimizations - Wenn true, weist der Debugger den Just-In-Time-Compiler an, Code mit deaktivierten Optimierungen zu generieren, sobald ein optimiertes Modul (in der Release-Konfiguration kompiliert) in den Zielprozess geladen wird. Mehr Informationen
• csharp.debug.symbolOptions.searchPaths - Array von Symbolserver-URLs (Beispiel: http://MeinBeispielSymbolServer) oder Verzeichnissen (Beispiel: /build/symbols), in denen nach .pdb-Dateien gesucht werden soll. Diese Verzeichnisse werden zusätzlich zu den Standardorten (neben dem Modul und dem ursprünglichen Pfad der pdb-Datei) durchsucht.
• csharp.debug.symbolOptions.searchMicrosoftSymbolServer - Wenn true, wird der Microsoft-Symbolserver (https://msdl.microsoft.com/download/symbols) zum Suchpfad hinzugefügt. Standardwert ist false.
• csharp.debug.symbolOptions.searchNuGetOrgSymbolServer - Wenn true, wird der NuGet.org-Symbolserver (https://symbols.nuget.org/download/symbols) zum Suchpfad hinzugefügt. Standardwert ist false.
• csharp.debug.symbolOptions.cachePath - Verzeichnis, in dem von Symbolservern heruntergeladene Symbole zwischengespeichert werden sollen. Falls nicht spezifiziert, verwendet der Debugger unter Windows standardmäßig %TEMP%\\SymbolCache und unter Linux/macOS ~/.dotnet/symbolcache.
• csharp.debug.symbolOptions.moduleFilter.mode - Steuert den Betriebsmodus des Modulfilters.
  • loadAllButExcluded - Lädt Symbole für alle Module, sofern das Modul nicht im Array excludedModules enthalten ist.
  • loadOnlyIncluded - Versucht nicht, Symbole für JEDES Modul zu laden, es sei denn, es ist im Array includedModules enthalten oder wird durch die Einstellung includeSymbolsNextToModules eingeschlossen.
• csharp.debug.symbolOptions.moduleFilter.excludedModules - Array von Modulen, für die der Debugger KEINE Symbole laden soll. Platzhalter (Beispiel: MyCompany.*.dll) werden unterstützt. Diese Eigenschaft wird ignoriert, wenn der Modus nicht auf loadAllButExcluded gesetzt ist.
• csharp.debug.symbolOptions.moduleFilter.includedModules - Array von Modulen, für die der Debugger Symbole laden soll. Platzhalter werden unterstützt. Diese Eigenschaft wird ignoriert, wenn der Modus nicht auf loadOnlyIncluded gesetzt ist.
• csharp.debug.symbolOptions.moduleFilter.includeSymbolsNextToModules - Wenn true, prüft der Debugger bei Modulen, die NICHT im Array includedModules enthalten sind, weiterhin neben dem Modul selbst und der ausführbaren Startdatei, jedoch nicht in den Pfaden der Symbol-Suchliste. Standardwert ist true. Diese Eigenschaft wird ignoriert, wenn der Modus nicht auf loadOnlyIncluded gesetzt ist.
• csharp.debug.allowFastEvaluate - Wenn true (Standard), versucht der Debugger eine schnellere Auswertung durch Simulation der Ausführung einfacher Eigenschaften und Methoden.
• csharp.experimental.debug.hotReload - Wenn true, ermöglicht der Debugger das Anwenden von Änderungen während des Debuggens, sofern die Zielanwendung Hot Reload unterstützt.
• csharp.debug.hotReloadOnSave - Wenn true (Standard), wendet der Debugger Codeänderungen automatisch beim Speichern der Datei an.
• csharp.debug.hotReloadVerbosity - Steuert die Ausführlichkeit der Protokollierung für das Ausgabefenster C# Hot Reload. Einstellbar auf minimal (Standard), detailed oder diagnostic.

Haltepunkte

Der C#-Debugger unterstützt verschiedene Breakpoints, wie Zeilen-Breakpoints, bedingte Breakpoints und Logpoints.

Breakpoint - Bedingter Breakpoint

Mithilfe der Ausdrucksauswertung unterstützt der Debugger auch bedingte Breakpoints. Sie können einen Breakpoint so setzen, dass die Ausführung nur stoppt, wenn ein Ausdruck als "wahr" ausgewertet wird.

Breakpoint - Funktions-Breakpoint

Der Debugger unterstützt auch funktionale Breakpoints. Sie können einen Breakpoint so einrichten, dass die Ausführung beim Erreichen einer bestimmten Funktion stoppt, indem Sie im Bereich "Breakpoints" der Debug-Ansicht auf + klicken.

Breakpoint - Logpoints

Logpoints (in Visual Studio auch als Tracepoints bezeichnet) ermöglichen es, Ausgaben in die Debug-Konsole zu senden, ohne den Code zu bearbeiten. Sie unterscheiden sich von Breakpoints dadurch, dass sie den Programmfluss nicht anhalten.

Um einen Logpoint hinzuzufügen, klicken Sie mit der rechten Maustaste in den Rand ganz links neben einer Codezeile. Wählen Sie Logpoint hinzufügen und geben Sie die Nachricht ein, die protokolliert werden soll. Jeder Ausdruck zwischen geschweiften Klammern ('{' und '}') wird beim Erreichen des Logpoints ausgewertet.

Die folgenden Token werden in der Log-Nachricht ebenfalls unterstützt:

Breakpoint - Ausgelöste Breakpoints

Ein ausgelöster Haltepunkt ist ein Haltepunkt, der automatisch aktiviert wird, sobald ein anderer Haltepunkt getroffen wird. Sie können sehr nützlich sein, um Fehlerfälle im Code zu diagnostizieren, die nur nach einer bestimmten Vorbedingung auftreten.

Ausgelöste Haltepunkte können durch Rechtsklick auf den Glyph-Rand gesetzt werden, indem Ausgelösten Haltepunkt hinzufügen ausgewählt und dann gewählt wird, welcher andere Haltepunkt den Haltepunkt aktiviert.

Anhalten bei Ausnahmen

Der C#-Debugger unterstützt Konfigurationsoptionen dafür, wann der Debugger bei geworfenen oder abgefangenen Ausnahmen stoppen soll. Dies erfolgt über zwei verschiedene Einträge im Abschnitt BREAKPOINTS der Run-Ansicht.

Beachten Sie, dass der Abschnitt BREAKPOINTS diese Einträge erst enthält, nachdem der Ordner zum ersten Mal mit dem C#-Debugger debuggt wurde.

Wenn Alle Ausnahmen aktiviert ist, hält der Debugger bei jeder geworfenen Ausnahme an. Wenn Just My Code aktiviert ist (Standard), stoppt der Debugger nicht, wenn eine Ausnahme intern in Bibliothekscode geworfen und abgefangen wird.

Wenn Benutzer-nicht abgefangene Ausnahmen aktiviert ist, hält der Debugger an, wenn eine Ausnahme in Nicht-Benutzercode abgefangen wird, nachdem sie im Benutzercode geworfen wurde oder diesen durchlaufen hat.

Ausnahmebedingungen

Beide Kontrollkästchen unterstützen Bedingungen, um nur bei ausgewählten Ausnahmetypen zu stoppen. Um die Bedingung zu bearbeiten, klicken Sie auf das Stift-Symbol oder rechtsklicken Sie auf den Eintrag und wählen Bedingung bearbeiten. Die Bedingung ist eine kommagetrennte Liste von Ausnahmetypen; beginnt die Liste mit '!', werden diese Typen ignoriert.

Beispielbedingungen

Auswertung von Ausdrücken

Der Debugger ermöglicht auch das Auswerten von Ausdrücken im ÜBERWACHUNG-Fenster sowie in der Debug-Konsole.

Hot Reload

Mit der installierten C# Dev Kit-Erweiterung können Sie während des Debuggens C#-Codeänderungen anwenden.

Um Hot Reload zu aktivieren, muss csharp.experimental.debug.hotReload auf true gesetzt sein. Siehe Benutzereinstellungen.

Unterstützte Projekte und Szenarien

C# Dev Kit unterstützt das "klassische" Hot Reload, auch bekannt als "Bearbeiten und Fortfahren". Sie können Codeänderungen während des Debuggens anwenden, unabhängig davon, ob Sie an einem Breakpoint gestoppt haben oder das Programm läuft.

Stand November 2023 sind einige Funktionen wie MetadataUpdateHandler noch nicht verfügbar. Das Anwenden von Codeänderungen ohne Debugging wird ebenfalls nicht unterstützt.

Die Laufzeitumgebung bietet seit .NET 8 Unterstützung für das Anwenden von Änderungen während des Debuggens unter Linux/macOS, daher ist .NET 8+ erforderlich.

Siehe unterstützte Projekte für weitere Informationen.

So wenden Sie Codeänderungen an

Sobald eine Hot-Reload-Sitzung startet und Änderungen vorgenommen wurden, können Sie diese über folgende Aktionen anwenden:

Nächste Schritte

Lesen Sie weiter, um mehr über Folgendes zu erfahren:

• Debuggen - Erfahren Sie, wie Sie den Debugger in VS Code für jedes Projekt und jede Sprache verwenden.