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 C# Dev Kit mehrere Möglichkeiten, Ihre C#-Anwendung auszuführen und zu debuggen.

Um ohne C# Dev Kit auszuführen und zu debuggen, finden Sie Dokumentationen auf der GitHub-Seite der Microsoft C#-Erweiterung.

Debuggen mit F5

Wenn die C# Dev Kit-Erweiterung installiert ist und keine Debug-Konfigurationen in der Debug-Ansicht ausgewählt werden können, 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 startet das Debuggen. Wenn Sie mehrere Projekte haben, werden Sie gefragt, welches Projekt Sie debuggen möchten.

Sie können eine Debugging-Sitzung auch über die Ansicht Ausführen und Debuggen in der Seitenleiste von VS Code starten. Weitere Informationen finden Sie unter Debuggen in VS Code.

Debuggen mit dem Solution Explorer

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

Es gibt drei Optionen

• Neue Instanz starten – Dies startet Ihr Projekt mit angehängtem Debugger.
• Ohne Debuggen starten – Dies führt Ihr Projekt ohne angehängten Debugger aus.
• In neue Instanz schrittweise ausführen – Dies startet Ihr Projekt mit angehängtem Debugger, hält aber am Einstiegspunkt Ihres Codes an.

Debuggen mit der Befehlspalette

Mit der installierten C# Dev Kit-Erweiterung können Sie das Debuggen auch über die Befehlspalette ⇧⌘P (Windows, Linux Ctrl+Shift+P) starten, indem Sie den Befehl Debuggen: Debugging auswählen und starten verwenden.

Hinweis: Dies fügt einen Eintrag für die Startkonfiguration zu Ihrer Debug-Dropdownliste hinzu.

Debuggen mit dynamischen (im Speicher befindlichen) Startkonfigurationen

Mit der C# Dev Kit-Erweiterung können Sie dynamische Startkonfigurationen erstellen. Wie Sie diese erstellen, hängt davon ab, ob Ihr Projekt eine vorhandene launch.json-Datei hat.

Vorhandene launch.json

Wenn Sie eine vorhandene launch.json-Datei haben, können Sie zur Debug-Ansicht gehen, die Dropdown-Liste auswählen und die Option C# auswählen. Dies sollte Ihnen eine Auswahl an Startzielen anzeigen, die Sie Ihrer Dropdown-Liste hinzufügen können. Nach der Auswahl können Sie F5 drücken oder Debugging starten mit der neu generierten Konfiguration.

Keine launch.json

Wenn Sie keine launch.json-Datei in Ihrem Projekt haben, können Sie diese dynamischen Konfigurationen im Alle automatischen Debug-Konfigurationen anzeigen in der Debug-Ansicht hinzufügen und darauf zugreifen.

Dynamische (im Speicher befindliche) Startkonfigurationen entfernen

Sie können die generierten Konfigurationen über die Befehlspalette ⇧⌘P (Windows, Linux Ctrl+Shift+P) und die Verwendung des Befehls Debuggen: Debugging auswählen und starten entfernen.

In der Dropdown-Liste werden alle Ihre vorhandenen Debug-Konfigurationen angezeigt. Wenn Sie mit der Maus über die dynamischen Konfigurationen fahren, erscheint rechts ein anklickbares Papierkorbsymbol. Sie können dieses Symbol auswählen, um die dynamische Konfiguration zu entfernen.

Debuggen mit Editor-Debug/Run-Schaltflächen

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 Editorfensters zugänglich. Diese Aktionen verwenden die aktuelle Datei, um das Projektsystem abzufragen und das zu startende Projekt zu ermitteln.

Die beiden Optionen sind

• Projekt zu dieser Datei ausführen: Dies startet Ihr Programm mit noDebug: true mit dem Debug-Adapter.
• Projekt zu dieser Datei debuggen: Dies startet Ihr Programm unter dem Debugger.

Debuggen mit launch.json

Wenn Sie C# Dev Kit verwenden, wird diese Option nicht empfohlen. Wenn Sie jedoch die Debug-Konfiguration direkt ändern müssen, lesen Sie bitte Konfigurieren von launch.json für C#-Debugging.

An einen Prozess anhängen

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

Konfigurationsoptionen

Es stehen viele Optionen und Einstellungen zur Konfiguration des Debuggers zur Verfügung. Sie können launchSettings.json, VS Code Benutzereinstellungen verwenden, um Ihre Debug-Optionen zu ändern, oder Ihre launch.json direkt ändern.

launchSettings.json

Wenn Sie launchSettings.json von Visual Studio haben, sollten Ihre Profile unter Ausführen ab F5 oder Ausführen ab Befehlspalette aufgeführt sein.

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

Benutzereinstellungen

Wenn Sie Einstellungen ändern möchten, während Sie den C#-Debugger verwenden, finden Sie diese Optionen unter Datei > Einstellungen (⌘, (Windows, Linux Ctrl+,)) und suchen Sie nach diesen Optionen.

• csharp.debug.stopAtEntry – Wenn true, sollte der Debugger am Einstiegspunkt des Ziels anhalten. Diese Option ist standardmäßig auf false gesetzt.
• csharp.debug.console – Beim Starten von Konsolenprojekten wird angegeben, in welche Konsole das Zielprogramm gestartet werden soll. **Hinweis:** Diese Option wird nur für den Debug-Konfigurationstyp 'dotnet' verwendet.
  • internalConsole [Standard] – Die Debug-Konsole von VS Code. Dieser Modus ermöglicht es Ihnen, Meldungen sowohl vom Debugger als auch vom Zielprogramm an einem Ort anzuzeigen. Weitere Details 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-Pfaden lokale Quellcode-Speicherorte zu. Alle Instanzen von Build-Pfaden werden durch den lokalen Quellcode-Pfad ersetzt.
    Beispiel
      {\"<build-path>\":\"<local-source-path>\"}
• csharp.debug.justMyCode – Wenn aktiviert (standardmäßig), zeigt der Debugger nur Benutzercode ("Mein Code") an und tritt schrittweise in diesen ein, wobei Systemcode und anderer Code, der optimiert ist oder keine Debugging-Symbole hat, ignoriert werden. Weitere Informationen.
• csharp.debug.requireExactSource – Flag, um zu verlangen, dass der aktuelle Quellcode mit der PDB übereinstimmt. Diese Option ist standardmäßig auf true gesetzt.
• csharp.debug.enableStepFiltering – Flag, um das Überspringen von Eigenschaften und Operatoren zu aktivieren. Diese Option ist standardmäßig auf true gesetzt.
• csharp.debug.logging.exceptions – Flag, um zu bestimmen, ob Ausnahmemeldungen im Ausgabefenster protokolliert werden sollen. Diese Option ist standardmäßig auf true gesetzt.
• csharp.debug.logging.moduleLoad – Flag, um zu bestimmen, ob Modul-Ladeereignisse im Ausgabefenster protokolliert werden sollen. Diese Option ist standardmäßig auf true gesetzt.
• csharp.debug.logging.programOutput – Flag, um zu bestimmen, ob die Programmausgabe im Ausgabefenster protokolliert werden soll, wenn kein externes Terminal verwendet wird. Diese Option ist standardmäßig auf true gesetzt.
• csharp.debug.logging.diagnosticsLog – Verschiedene Einstellungen zur Diagnose von Problemen mit dem Debugger.
• csharp.debug.logging.browserStdOut – Flag, um zu bestimmen, ob die Standardausgabe des Webbrowsers beim Starten im Ausgabefenster protokolliert werden soll. Diese Option ist standardmäßig auf true gesetzt.
• csharp.debug.logging.elapsedTiming – Wenn true, enthält die Adapterprotokollierung die Eigenschaften adapterElapsedTime und engineElapsedTime, um die Zeit in Mikrosekunden anzugeben, die eine Anforderung gedauert hat. Diese Option ist standardmäßig auf false gesetzt.
• csharp.debug.logging.threadExit – Steuert, ob beim Beenden eines Threads im Zielprozess eine Meldung protokolliert wird. Diese Option ist standardmäßig auf false gesetzt.
• csharp.debug.logging.processExit – Steuert, ob beim Beenden des Zielprozesses oder beim Stoppen des Debuggens eine Meldung protokolliert wird. Diese Option ist standardmäßig auf true gesetzt.
• csharp.debug.suppressJITOptimizations – Wenn true, fordert der Debugger beim Laden eines optimierten Moduls (.dll, kompiliert in der Release-Konfiguration) den Just-In-Time-Compiler auf, Code mit deaktivierten Optimierungen zu generieren. Weitere Informationen
• csharp.debug.symbolOptions.searchPaths – Array von Symbolserver-URLs (Beispiel: http://MyExampleSymbolServer) oder Verzeichnissen (Beispiel: /build/symbols) zum Suchen nach .pdb-Dateien. Diese Verzeichnisse werden zusätzlich zu den Standardorten neben dem Modul und dem Pfad, auf dem die PDB ursprünglich abgelegt wurde, durchsucht.
• csharp.debug.symbolOptions.searchMicrosoftSymbolServer – Wenn true, wird der Microsoft Symbol Server (https://msdl.microsoft.com/download/symbols) zum Suchpfad für Symbole hinzugefügt. Wenn nicht angegeben, ist diese Option standardmäßig auf false gesetzt.
• csharp.debug.symbolOptions.searchNuGetOrgSymbolServer – Wenn true, wird der NuGet.org-Symbolserver (https://symbols.nuget.org/download/symbols) zum Suchpfad für Symbole hinzugefügt. Wenn nicht angegeben, ist diese Option standardmäßig auf false gesetzt.
• csharp.debug.symbolOptions.cachePath – Verzeichnis, in dem Symbole von Symbolservern heruntergeladen und zwischengespeichert werden sollen. Wenn nicht angegeben, verwendet der Debugger unter Windows standardmäßig %TEMP%\SymbolCache und unter Linux und macOS ~/.dotnet/symbolcache.
• csharp.debug.symbolOptions.moduleFilter.mode – Steuert, in welchem der beiden grundlegenden Betriebsmodi der Modulfilter arbeitet.
  • loadAllButExcluded – Lädt Symbole für alle Module, es sei denn, das Modul befindet sich im Array excludedModules.
  • loadOnlyIncluded – Versucht nicht, Symbole für IRGENDEIN Modul zu laden, es sei denn, es befindet sich im Array includedModules oder es wird über 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, es sei denn, mode ist auf loadAllButExcluded gesetzt.
• csharp.debug.symbolOptions.moduleFilter.includedModules – Array von Modulen, für die der Debugger Symbole laden soll. Platzhalter (Beispiel: MyCompany.*.dll) werden unterstützt. Diese Eigenschaft wird ignoriert, es sei denn, mode ist auf loadOnlyIncluded gesetzt.
• csharp.debug.symbolOptions.moduleFilter.includeSymbolsNextToModules – Wenn true, prüft der Debugger für jedes Modul, das NICHT im Array includedModules enthalten ist, neben dem Modul selbst und der startenden ausführbaren Datei, wird aber nicht die Pfade in der Symbolsuchliste prüfen. Diese Option ist standardmäßig auf true gesetzt. Diese Eigenschaft wird ignoriert, es sei denn, mode ist auf loadOnlyIncluded gesetzt.
• csharp.debug.allowFastEvaluate – Wenn true (Standardzustand), versucht der Debugger eine schnellere Auswertung, indem einfache Eigenschaften und Methoden simuliert werden.
• csharp.experimental.debug.hotReload – Wenn true, aktiviert der Debugger das Anwenden von Änderungen während des Debuggens, wenn die Zielanwendung Hot Reload unterstützt.
• csharp.debug.hotReloadOnSave – Wenn true (Standardzustand), wendet der Debugger automatisch Codeänderungen an, wenn die Datei gespeichert wird.
• csharp.debug.hotReloadVerbosity – Steuert die Protokollierungsdetailliertheit für das Ausgabefenster C# Hot Reload. Es kann auf minimal (Standard), detailed oder diagnostic eingestellt werden. Es wird empfohlen, die Detailliertheit zu erhöhen, wenn Hot Reload unerwartet reagiert.

Haltepunkte

Der C#-Debugger unterstützt verschiedene Breakpoints, wie z. B. Source-Line-Breakpoints, bedingte Breakpoints und Logpoints.

Breakpoint – Bedingter Breakpoint

Mithilfe der Auswertung von Ausdrücken unterstützt der Debugger auch bedingte Breakpoints. Sie können Ihren Breakpoint so einstellen, dass er unterbrochen wird, wenn ein Ausdruck zu true ausgewertet wird.

Breakpoint – Funktions-Breakpoint

Der Debugger unterstützt auch funktionale Breakpoints. Sie können Ihren Breakpoint so einstellen, dass er an der spezifischen Funktion unterbrochen wird, indem Sie auf das + im Abschnitt Breakpoints des Debug-Bereichs klicken.

Breakpoint – Logpoints

Logpoints (auch Tracepoints in Visual Studio genannt) ermöglichen es Ihnen, Ausgaben an die Debug-Konsole zu senden, ohne den Code zu ändern. Sie unterscheiden sich von Breakpoints dadurch, dass sie den Ausführungsfluss Ihrer Anwendung nicht stoppen.

Um einen Logpoint hinzuzufügen, klicken Sie mit der rechten Maustaste in den äußersten linken Rand neben einer Codezeile. Wählen Sie Logpoint hinzufügen und geben Sie die zu protokollierende Nachricht ein. Jeder Ausdruck in geschweiften Klammern ('{' und '}') wird ausgewertet, wenn der Logpoint getroffen wird.

Die folgenden Tokens werden ebenfalls in der Log-Nachricht 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 für das Anhalten, wenn Ausnahmen ausgelöst oder abgefangen werden. Dies geschieht über zwei verschiedene Einträge im Abschnitt BREAKPOINTS der Ansicht Run.

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

Wenn Sie Alle Ausnahmen aktivieren, wird der Debugger so konfiguriert, dass er anhält, wenn eine Ausnahme ausgelöst wird. Wenn Just My Code aktiviert ist (was standardmäßig der Fall ist), wird der Debugger nicht unterbrochen, wenn eine Ausnahme intern in Bibliotheks-Code ausgelöst und abgefangen wird. Wenn die Ausnahme jedoch im Bibliotheks-Code ausgelöst und an den Benutzercode zurückgegeben wird, wird der Debugger unterbrochen.

Wenn Sie Benutzerunbehandelte Ausnahmen aktivieren, wird der Debugger so konfiguriert, dass er anhält, wenn eine Ausnahme in Nicht-Benutzercode abgefangen wird, nachdem sie im Benutzercode ausgelöst wurde oder durch den Benutzercode gelaufen ist. Ausnahmen, die benutzerunbehandelt werden, sind nicht immer ein Fehler im zu debuggenden Prozess – es kann sein, dass Benutzercode eine API implementiert und eine Ausnahme auslösen soll. In vielen Fällen liegt ein tatsächliches Problem vor, daher hält der Debugger standardmäßig an, wenn eine Ausnahme benutzerunbehandelt wird.

Ausnahmebedingungen

Beide Kontrollkästchen unterstützen Bedingungen, um nur bei ausgewählten Ausnahmetypen zu brechen. Um die Bedingung zu bearbeiten, wählen Sie das Stiftsymbol (siehe obiges Bild) oder klicken Sie mit der rechten Maustaste auf den Eintrag und rufen Sie Bedingung bearbeiten auf. Die Bedingung ist eine kommagetrennte Liste von Ausnahmetypen, bei denen gebrochen werden soll, oder wenn die Liste mit '!' beginnt, eine Liste von Ausnahmetypen, die ignoriert werden sollen.

Beispielbedingungen

Auswertung von Ausdrücken

Der Debugger ermöglicht es Ihnen auch, Ausdrücke im WATCH-Fenster sowie in der Debug-Konsole auszuwerten.

Hot Reload

Mit der installierten C# Dev Kit-Erweiterung ermöglicht Ihnen der Debugger das Anwenden von C#-Codeänderungen während des Debuggens.

Um Hot Reload zu aktivieren, muss csharp.experimental.debug.hotReload auf true gesetzt sein. Weitere Informationen finden Sie unter Benutzereinstellungen. Die Hot Reload-Sitzung wird nur gestartet, wenn die Ziel-Debugger-Engine das Anwenden von Codeänderungen unterstützt.

Unterstützte Projekte und Szenarien

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

Seit November 2023 sind einige Funktionen wie MetadataUpdateHandler, die es ASP.NET Core-Anwendungen ermöglichen, den Browser nach einer Änderung automatisch zu aktualisieren, noch nicht verfügbar. Das Anwenden von Codeänderungen ohne Debugging wird ebenfalls nicht unterstützt.

Die Laufzeitumgebung unterstützt das Anwenden von Änderungen während des Debuggens unter Linux/macOS in .NET 8, sodass eine Laufzeitversion von .NET 8+ erforderlich ist, wenn Codeänderungen für .NET-Apps auf diesen Betriebssystemen angewendet werden.

Weitere Informationen zu den von C# Dev Kit derzeit unterstützten Projekten finden Sie unter unterstützte Projekte. Weitere Informationen zur Fehlerbehebung bei anderen nicht unterstützten Szenarien finden Sie auch im C# Dev Kit FAQ.

Anwenden von Codeänderungen

Sobald eine Hot Reload-Sitzung gestartet wurde und neue Änderungen vorgenommen wurden, können Sie diese Änderungen mit einer der folgenden Aktionen auf Ihre Anwendung anwenden.

Nächste Schritte

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

• Debuggen – Finden Sie heraus, wie Sie den Debugger in VS Code mit Ihrem Projekt für jede Sprache verwenden.