Visual Studio Code Debug-Konfiguration

Für komplexe Debugging-Szenarien oder Anwendungen müssen Sie eine launch.json-Datei erstellen, um die Debugger-Konfiguration festzulegen. Zum Beispiel, um den Einstiegspunkt der Anwendung anzugeben, sich an eine laufende Anwendung anzuhängen (Attach) oder Umgebungsvariablen zu setzen.

Um mehr über das Debuggen in VS Code zu erfahren, lesen Sie Debuggen in Visual Studio Code.

Startkonfigurationen

Für einfache Anwendungen oder Debugging-Szenarien können Sie ein Programm ohne spezielle Debugging-Konfigurationen ausführen und debuggen. Verwenden Sie die Taste F5, und VS Code wird versuchen, Ihre aktuell aktive Datei auszuführen.

Für die meisten Debugging-Szenarien müssen Sie jedoch eine Debugging-Konfiguration (Startkonfiguration) erstellen. Zum Beispiel, um den Einstiegspunkt der Anwendung anzugeben, sich an eine laufende Anwendung anzuhängen oder Umgebungsvariablen zu setzen. Das Erstellen einer Startkonfigurationsdatei ist auch deshalb vorteilhaft, weil Sie damit die Debugging-Einrichtung zusammen mit Ihrem Projekt konfigurieren und speichern können.

VS Code speichert Informationen zur Debugging-Konfiguration in einer launch.json-Datei, die sich im .vscode-Ordner in Ihrem Arbeitsbereich (Projektstammordner) oder in Ihren Benutzereinstellungen bzw. Arbeitsbereichseinstellungen befindet.

Der folgende Ausschnitt beschreibt eine Beispielkonfiguration für das Debuggen einer Node.js-Anwendung

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}\\app.js"
    }
  ]
}

VS Code unterstützt auch zusammengesetzte Startkonfigurationen (Compound) zum gleichzeitigen Starten mehrerer Konfigurationen.

Erstellen einer Debug-Konfigurationsdatei

Erstellen einer initialen launch.json-Datei

1. Wählen Sie launch.json-Datei erstellen in der Ansicht „Ausführen und Debuggen“.

   

2. VS Code versucht, Ihre Debug-Umgebung zu erkennen. Wenn dies nicht möglich ist, können Sie sie manuell auswählen.

   

   Basierend auf der ausgewählten Debug-Umgebung erstellt VS Code eine Startkonfiguration in der launch.json-Datei.

3. Beachten Sie in der Explorer-Ansicht (⇧⌘E (Windows, Linux Ctrl+Shift+E)), dass VS Code einen .vscode-Ordner erstellt und die launch.json-Datei zu Ihrem Arbeitsbereich hinzugefügt hat.

   

Sie können nun die launch.json-Datei bearbeiten, um weitere Konfigurationen hinzuzufügen oder bestehende zu ändern.

Hinzufügen einer Konfiguration zur launch.json

Um eine neue Konfiguration zu einer bestehenden launch.json hinzuzufügen, verwenden Sie eine der folgenden Methoden:

• Drücken Sie die Schaltfläche Konfiguration hinzufügen und wählen Sie dann ein Snippet aus, um eine vordefinierte Konfiguration hinzuzufügen.
• Verwenden Sie IntelliSense, wenn sich Ihr Cursor innerhalb des Konfigurations-Arrays befindet.
• Wählen Sie die Menüoption Ausführen > Konfiguration hinzufügen.

Generieren einer Startkonfiguration mit KI

Mit Copilot in VS Code können Sie den Prozess zur Erstellung einer Startkonfiguration für Ihr Projekt beschleunigen. So generieren Sie eine Startkonfiguration mit Copilot:

1. Öffnen Sie die Chat-Ansicht mit ⌃⌘I (Windows, Linux Ctrl+Alt+I) oder wählen Sie Chat öffnen aus dem Copilot-Menü in der Titelleiste.

2. Geben Sie den Chat-Befehl /startDebugging ein, um eine Debug-Konfiguration zu generieren.

   Alternativ können Sie auch eine benutzerdefinierte Eingabeaufforderung eingeben, wie z. B. generate a debug config for an express app #codebase.

   Dies kann nützlich sein, wenn Ihr Arbeitsbereich Dateien in verschiedenen Sprachen enthält.

   Hinweis

   Die Chat-Variable #codebase gibt Copilot den Kontext Ihres Projekts, was dabei hilft, eine genauere Antwort zu generieren.

3. Übernehmen Sie die vorgeschlagene Konfiguration und starten Sie dann das Debuggen.

Starten einer Debug-Sitzung mit einer Startkonfiguration

Starten einer Debug-Sitzung mit einer Startkonfiguration

1. Wählen Sie die Konfiguration mit dem Namen Launch Program über das Konfigurations-Dropdown in der Ansicht Ausführen und Debuggen aus.

   Die Liste der verfügbaren Konfigurationen entspricht denen in der launch.json-Datei.

   

2. Starten Sie Ihre Debug-Sitzung mit F5 oder wählen Sie Debuggen starten (Wiedergabesymbol) in der Ansicht Ausführen und Debuggen.

Alternativ können Sie Ihre Konfiguration über die Befehlspalette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) ausführen, indem Sie nach Debug: Select and Start Debugging filtern oder 'debug ' eingeben und die Konfiguration auswählen, die Sie debuggen möchten.

Start- versus Anfüge-Konfigurationen (Launch vs. Attach)

In VS Code gibt es zwei grundlegende Debugging-Modi: Start (Launch) und Anhängen (Attach). Diese bedienen unterschiedliche Arbeitsabläufe und Entwicklergruppen. Abhängig von Ihrem Arbeitsablauf kann es verwirrend sein, welcher Konfigurationstyp für Ihr Projekt geeignet ist.

Wenn Sie aus dem Bereich der Browser-Entwicklertools kommen, sind Sie möglicherweise nicht daran gewöhnt, „aus Ihrem Tool zu starten“, da Ihre Browser-Instanz bereits geöffnet ist. Wenn Sie DevTools öffnen, hängen Sie die DevTools einfach an Ihren geöffneten Browsertab an. Wenn Sie hingegen aus dem Server- oder Desktop-Bereich kommen, ist es durchaus üblich, dass Ihr Editor den Prozess für Sie startet und der Debugger automatisch an diesen neu gestarteten Prozess angehängt wird.

Der beste Weg, den Unterschied zwischen Start und Anfügen zu erklären, besteht darin, eine Startkonfiguration als Rezept zu betrachten, wie Ihre App im Debug-Modus gestartet wird, bevor VS Code sich anhängt, während eine Anfüge-Konfiguration ein Rezept dafür ist, wie sich der Debugger von VS Code mit einer App oder einem Prozess verbindet, der bereits läuft.

VS Code-Debugger unterstützen typischerweise das Starten eines Programms im Debug-Modus oder das Anhängen an ein bereits laufendes Programm im Debug-Modus. Abhängig von der Anfrage (attach oder launch) sind unterschiedliche Attribute erforderlich; die launch.json-Validierung und -Vorschläge von VS Code sollten dabei helfen.

Launch.json-Attribute

Es gibt viele launch.json-Attribute, die verschiedene Debugger und Debugging-Szenarien unterstützen. Sie können IntelliSense (⌃Space (Windows, Linux Ctrl+Space)) verwenden, um die Liste der verfügbaren Attribute zu sehen, sobald Sie einen Wert für das type-Attribut angegeben haben. Die in Startkonfigurationen verfügbaren Attribute variieren von Debugger zu Debugger.

Ein Attribut, das für einen Debugger verfügbar ist, funktioniert nicht automatisch auch für andere. Wenn Sie rote Wellenlinien in Ihrer Startkonfiguration sehen, bewegen Sie den Mauszeiger darüber, um das Problem zu erfahren, und versuchen Sie es zu beheben, bevor Sie eine Debug-Sitzung starten.

Die folgenden Attribute sind für jede Startkonfiguration zwingend erforderlich:

• type – der Typ des Debuggers, der für diese Startkonfiguration verwendet werden soll. Jede installierte Debug-Erweiterung führt einen Typ ein: z. B. node für den integrierten Node-Debugger oder php und go für die PHP- und Go-Erweiterungen.
• request – der Anfragetyp dieser Startkonfiguration. Aktuell werden launch Open in VS Code Open in VS Code Insiders und attach unterstützt.
• name – der benutzerfreundliche Name, der im Dropdown-Menü für Debug-Startkonfigurationen erscheint.

Hier sind einige optionale Attribute, die für alle Startkonfigurationen verfügbar sind:

• presentation – mithilfe der Attribute order, group und hidden im presentation-Objekt können Sie Konfigurationen und Compounds im Debug-Konfigurations-Dropdown und in der Debug-Schnellauswahl sortieren, gruppieren und ausblenden. Sie können presentation auch innerhalb von plattformspezifischen Abschnitten (windows, linux, osx) festlegen, um die Sichtbarkeit je nach Betriebssystem zu steuern.
• preLaunchTask – um eine Aufgabe vor Beginn einer Debug-Sitzung zu starten, setzen Sie dieses Attribut auf die Bezeichnung einer Aufgabe, die in tasks.json (im .vscode-Ordner des Arbeitsbereichs) definiert ist. Alternativ kann dies auf ${defaultBuildTask} gesetzt werden, um Ihre Standard-Build-Aufgabe zu verwenden.
• postDebugTask – um am Ende einer Debug-Sitzung eine Aufgabe zu starten, setzen Sie dieses Attribut auf den Namen einer Aufgabe, die in tasks.json (im .vscode-Ordner des Arbeitsbereichs) definiert ist.
• internalConsoleOptions – dieses Attribut steuert die Sichtbarkeit des Debug-Konsolenbereichs während einer Debug-Sitzung.
• debugServer – nur für Autoren von Debug-Erweiterungen: dieses Attribut ermöglicht es Ihnen, sich mit einem bestimmten Port zu verbinden, anstatt den Debug-Adapter zu starten.
• serverReadyAction – wenn Sie eine URL in einem Webbrowser öffnen möchten, sobald das Programm unter Debugging eine bestimmte Nachricht an die Debug-Konsole oder das integrierte Terminal ausgibt. Details finden Sie im Abschnitt Automatisches Öffnen einer URI beim Debuggen eines Serverprogramms unten.

Viele Debugger unterstützen einige der folgenden Attribute:

• program – ausführbare Datei oder Datei, die beim Starten des Debuggers ausgeführt werden soll
• args – Argumente, die an das zu debuggende Programm übergeben werden
• env – Umgebungsvariablen (der Wert null kann verwendet werden, um eine Variable „undefiniert“ zu machen)
• envFile – Pfad zur dotenv-Datei mit Umgebungsvariablen
• cwd – aktuelles Arbeitsverzeichnis zum Auffinden von Abhängigkeiten und anderen Dateien
• port – Port beim Anhängen an einen laufenden Prozess
• stopOnEntry – sofort unterbrechen, wenn das Programm startet
• console – welche Art von Konsole verwendet werden soll, zum Beispiel internalConsole, integratedTerminal oder externalTerminal

Variablensubstitution

VS Code stellt häufig verwendete Pfade und andere Werte als Variablen zur Verfügung und unterstützt Variablensubstitution innerhalb von Zeichenfolgen in launch.json. Das bedeutet, dass Sie keine absoluten Pfade in Debug-Konfigurationen verwenden müssen. Beispielsweise liefert ${workspaceFolder} den Stammpfad eines Arbeitsbereichsordners, ${file} die im aktiven Editor geöffnete Datei und ${env:Name} die Umgebungsvariable 'Name'.

Sie finden eine vollständige Liste vordefinierter Variablen in der Variablenreferenz oder durch Aufrufen von IntelliSense innerhalb der launch.json-String-Attribute.

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",
  "cwd": "${workspaceFolder}",
  "args": ["${env:USERNAME}"]
}

Plattformspezifische Eigenschaften

VS Code unterstützt die Definition von Debugging-Konfigurationseinstellungen (z. B. Argumente, die an das Programm übergeben werden), die vom Betriebssystem abhängen, auf dem der Debugger läuft. Platzieren Sie dazu ein plattformspezifisches Literal in der launch.json-Datei und geben Sie die entsprechenden Eigenschaften innerhalb dieses Literals an.

Das folgende Beispiel zeigt, wie "args" unter Windows unterschiedlich an das Programm übergeben werden können:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
      "args": ["myFolder/path/app.js"],
      "windows": {
        "args": ["myFolder\\path\\app.js"]
      }
    }
  ]
}

Gültige Betriebssystem-Eigenschaften sind "windows" für Windows, "linux" für Linux und "osx" für macOS. Eigenschaften, die in einem betriebssystemspezifischen Bereich definiert sind, überschreiben Eigenschaften, die im globalen Bereich definiert wurden.

Die type-Eigenschaft kann nicht innerhalb eines plattformspezifischen Abschnitts platziert werden, da type in Remote-Debugging-Szenarien indirekt die Plattform bestimmt, was zu einer zyklischen Abhängigkeit führen würde.

Im folgenden Beispiel stoppt das Debuggen des Programms immer beim Einstieg (stop on entry), außer unter macOS:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/node_modules/gulp/bin/gulpfile.js",
      "stopOnEntry": true,
      "osx": {
        "stopOnEntry": false
      }
    }
  ]
}

Sie können auch plattformspezifische Abschnitte verwenden, um presentation-Eigenschaften zu steuern. Im folgenden Beispiel ist die Konfiguration unter macOS im Debug-Dropdown ausgeblendet:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/app.js",
      "osx": {
        "presentation": {
          "hidden": true
        }
      }
    }
  ]
}

Globale Startkonfiguration

Sie können Startkonfigurationen definieren, die in all Ihren Arbeitsbereichen verfügbar sind. Um eine globale Startkonfiguration festzulegen, fügen Sie ein Startkonfigurationsobjekt in Ihre launch Open in VS Code Open in VS Code Insiders Benutzereinstellung hinzu. Diese launch-Konfiguration wird dann über Ihre Arbeitsbereiche hinweg geteilt. Zum Beispiel:

"launch": {
    "version": "0.2.0",
    "configurations": [{
        "type": "node",
        "request": "launch",
        "name": "Launch Program",
        "program": "${file}"
    }]
}

Umleiten von Ein-/Ausgabe zum/vom Debug-Ziel

Das Umleiten von Ein-/Ausgabe ist Debugger- oder Laufzeit-spezifisch, daher bietet VS Code keine integrierte Lösung, die für alle Debugger funktioniert.

Hier sind zwei Ansätze, die Sie in Betracht ziehen könnten:

• Starten Sie das Programm zum Debuggen („Debug-Ziel“) manuell in einem Terminal oder einer Eingabeaufforderung und leiten Sie Ein-/Ausgabe nach Bedarf um. Stellen Sie sicher, dass Sie die entsprechenden Befehlszeilenoptionen an das Debug-Ziel übergeben, damit ein Debugger daran anhängen kann. Erstellen und starten Sie eine „Anfüge“-Debug-Konfiguration, die sich an das Debug-Ziel hängt.

• Wenn die von Ihnen verwendete Debugger-Erweiterung das Debug-Ziel im integrierten Terminal von VS Code (oder einem externen Terminal) ausführen kann, können Sie versuchen, die Shell-Umleitungssyntax (z. B. „<“ oder „>“) als Argumente zu übergeben.

  Hier ist eine Beispiel-launch.json-Konfiguration:

  {
    "name": "launch program that reads a file from stdin",
    "type": "node",
    "request": "launch",
    "program": "program.js",
    "console": "integratedTerminal",
    "args": ["<", "in.txt"]
  }
  

  Dieser Ansatz erfordert, dass die <-Syntax durch die Debugger-Erweiterung geleitet wird und unverändert im integrierten Terminal landet.

Zusammengesetzte Startkonfigurationen (Compound)

Eine alternative Möglichkeit, mehrere Debug-Sitzungen zu starten, ist die Verwendung einer zusammengesetzten Startkonfiguration (Compound). Sie können diese Konfigurationen in der compounds-Eigenschaft in der launch.json-Datei definieren.

Verwenden Sie das Attribut configurations, um die Namen von zwei oder mehr Startkonfigurationen aufzulisten, die parallel gestartet werden sollen.

Optional können Sie eine preLaunchTask-Aufgabe angeben, die ausgeführt wird, bevor die einzelnen Debug-Sitzungen gestartet werden. Das boolesche Flag stopAll steuert, ob das manuelle Beenden einer Sitzung alle zusammengesetzten Sitzungen beendet.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Server",
      "program": "${workspaceFolder}/server.js"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Client",
      "program": "${workspaceFolder}/client.js"
    }
  ],
  "compounds": [
    {
      "name": "Server/Client",
      "configurations": ["Server", "Client"],
      "preLaunchTask": "${defaultBuildTask}",
      "stopAll": true
    }
  ]
}

Zusammengesetzte Startkonfigurationen werden ebenfalls im Dropdown-Menü für Startkonfigurationen angezeigt.

Automatisches Öffnen einer URI beim Debuggen eines Serverprogramms

Die Entwicklung eines Webprogramms erfordert normalerweise das Öffnen einer bestimmten URL in einem Webbrowser, um den Server-Code im Debugger zu erreichen. VS Code verfügt über eine integrierte Funktion „serverReadyAction“, um diese Aufgabe zu automatisieren.

Hier ist ein Beispiel für eine einfache Node.js Express-Anwendung:

var express = require('express');
var app = express();

app.get('/', function(req, res) {
  res.send('Hello World!');
});

app.listen(3000, function() {
  console.log('Example app listening on port 3000!');
});

Diese Anwendung installiert zuerst einen „Hello World“-Handler für die URL „/“ und beginnt dann, auf HTTP-Verbindungen am Port 3000 zu warten. Der Port wird in der Debug-Konsole angekündigt, und normalerweise würde der Entwickler nun https://:3000 in seinen Browser eingeben.

Die serverReadyAction-Funktion macht es möglich, eine strukturierte Eigenschaft serverReadyAction zu jeder Startkonfiguration hinzuzufügen und eine „Aktion“ auszuwählen, die ausgeführt werden soll:

{
  "type": "node",
  "request": "launch",
  "name": "Launch Program",
  "program": "${workspaceFolder}/app.js",

  "serverReadyAction": {
    "pattern": "listening on port ([0-9]+)",
    "uriFormat": "https://:%s",
    "action": "openExternally"
  }
}

Hier beschreibt die pattern-Eigenschaft den regulären Ausdruck für den Abgleich der Ausgabeseichenfolge des Programms, die den Port ankündigt. Das Muster für die Portnummer wird in Klammern gesetzt, damit es als Capture-Gruppe für reguläre Ausdrücke verfügbar ist. In diesem Beispiel extrahieren wir nur die Portnummer, aber es ist auch möglich, eine vollständige URI zu extrahieren.

Die uriFormat-Eigenschaft beschreibt, wie die Portnummer in eine URI umgewandelt wird. Das erste %s wird durch die erste Capture-Gruppe des passenden Musters ersetzt.

Die resultierende URI wird dann außerhalb von VS Code („extern“) mit der Standardanwendung geöffnet, die für das URI-Schema konfiguriert ist.

Debuggen über Microsoft Edge oder Chrome auslösen

Alternativ kann die action auf debugWithEdge oder debugWithChrome gesetzt werden. In diesem Modus kann eine webRoot-Eigenschaft hinzugefügt werden, die an die Chrome- oder Microsoft Edge-Debug-Sitzung übergeben wird.

Um die Dinge etwas zu vereinfachen, sind die meisten Eigenschaften optional, und wir verwenden die folgenden Fallback-Werte:

• pattern: "listening on.* (https?://\\S+|[0-9]+)", was auf häufig verwendete Nachrichten wie „listening on port 3000“ oder „Now listening on: https://:5001“ passt.
• uriFormat: "https://:%s"
• webRoot: "${workspaceFolder}"

Auslösen einer beliebigen Startkonfiguration

In einigen Fällen müssen Sie möglicherweise weitere Optionen für die Browser-Debug-Sitzung konfigurieren oder einen völlig anderen Debugger verwenden. Sie können dies tun, indem Sie action auf startDebugging setzen und eine name-Eigenschaft auf den Namen der Startkonfiguration setzen, die gestartet werden soll, wenn das pattern übereinstimmt.

Die benannte Startkonfiguration muss sich in derselben Datei oder demselben Ordner befinden wie die Konfiguration mit serverReadyAction.

Hier ist die serverReadyAction-Funktion in Aktion:

Nächste Schritte

• Tasks (Aufgaben) – Beschreibt, wie Aufgaben mit Gulp, Grunt und Jake ausgeführt werden und wie Fehler und Warnungen angezeigt werden.
• Variablenreferenz – Beschreibt die in VS Code verfügbaren Variablen.

Häufig gestellte Fragen

Ich sehe keine Startkonfigurationen im Dropdown der Ansicht „Ausführen und Debuggen“. Was stimmt nicht?

Das häufigste Problem ist, dass Sie launch.json nicht eingerichtet haben oder sich ein Syntaxfehler in dieser Datei befindet. Alternativ müssen Sie möglicherweise einen Ordner öffnen, da das Debuggen ohne Ordner keine Startkonfigurationen unterstützt.