Visual Studio Code Debug-Konfiguration

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

Um mehr über das Debugging in VS Code zu erfahren, siehe Debugging in Visual Studio Code.

Startkonfigurationen

Für einfache Anwendungen oder Debugging-Szenarien können Sie ein Programm ohne spezifische Debugging-Konfigurationen ausführen und debuggen. Verwenden Sie die Taste F5 und VS Code versucht, 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 festzulegen. Das Erstellen einer Startkonfigurationsdatei ist auch von Vorteil, da Sie damit Debugging-Einrichtungsdetails mit Ihrem Projekt konfigurieren und speichern können.

VS Code speichert Debugging-Konfigurationsinformationen in einer launch.json-Datei im Ordner .vscode in Ihrem Arbeitsbereich (Projektstammordner) oder in Ihren Benutzereinstellungen oder Arbeitsbereichseinstellungen.

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 verknüpfte Startkonfigurationen zum gleichzeitigen Starten mehrerer Konfigurationen.

Erstellen einer Debug-Konfigurationsdatei

So erstellen Sie eine initiale launch.json-Datei

1. Wählen Sie im Ansichtsfenster "Ausführen und Debuggen" die Option launch.json-Datei erstellen.

   

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. Im Explorer-Ansichtsfenster (⇧⌘E (Windows, Linux Ctrl+Shift+E)) beachten Sie, dass VS Code einen Ordner .vscode erstellt und die Datei launch.json zu Ihrem Arbeitsbereich hinzugefügt hat.

   

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

Konfiguration zu launch.json hinzufügen

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

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

Startkonfiguration mit KI generieren

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

1. Öffnen Sie das Chat-Fenster 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-Prompt /startDebugging ein, um eine Debug-Konfiguration zu generieren.

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

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

   Hinweis

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

3. Wenden Sie die vorgeschlagene Konfiguration an und starten Sie dann das Debugging.

Starten einer Debugging-Sitzung mit einer Startkonfiguration

So starten Sie eine Debug-Sitzung mit einer Startkonfiguration

1. Wählen Sie die Konfiguration mit dem Namen Programm starten über das Konfigurationsdropdown im Ansichtsfenster Ausführen und Debuggen.

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

   

2. Starten Sie Ihre Debug-Sitzung mit F5 oder wählen Sie Debugging starten (Play-Symbol) im Ansichtsfenster 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: Debugging auswählen und starten filtern oder 'debug ' eingeben und die zu debuggende Konfiguration auswählen.

Start- vs. Anfügekonfigurationen

In VS Code gibt es zwei Kern-Debugging-Modi, Starten (Launch) und Anfügen (Attach), die zwei verschiedene Workflows und Entwicklersegmente abdecken. Abhängig von Ihrem Workflow kann es verwirrend sein zu wissen, welcher Konfigurationstyp für Ihr Projekt geeignet ist.

Wenn Sie aus dem Hintergrund der Browser-Entwicklertools kommen, sind Sie es vielleicht nicht gewohnt, "von Ihrem Werkzeug aus zu starten", da Ihre Browserinstanz bereits geöffnet ist. Wenn Sie DevTools öffnen, hängen Sie DevTools einfach an Ihren geöffneten Browser-Tab an. Auf der anderen Seite ist es für Sie, der aus dem Server- oder Desktop-Hintergrund kommt, ganz normal, dass Ihr Editor Ihren Prozess für Sie startet und Ihr Editor automatisch seinen Debugger an den neu gestarteten Prozess anhängt.

Der beste Weg, den Unterschied zwischen Starten und Anhängen zu erklären, ist, eine Startkonfiguration als Rezept dafür zu betrachten, wie Ihre App im Debug-Modus gestartet wird, bevor VS Code sich daran anhängt, während eine Anfügekonfiguration ein Rezept dafür ist, wie Sie den Debugger von VS Code mit einer App oder einem Prozess verbinden, 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. Je nach Anforderung (attach oder launch) sind unterschiedliche Attribute erforderlich, und die launch.json-Validierung und Vorschläge von VS Code sollten dabei helfen.

Launch.json-Attribute

Es gibt viele launch.json-Attribute, um verschiedene Debugger und Debugging-Szenarien zu unterstützen. Sie können IntelliSense (⌃Space (Windows, Linux Ctrl+Space)) verwenden, um die Liste der verfügbaren Attribute anzuzeigen, sobald Sie einen Wert für das Attribut type 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 Debugger. Wenn Sie rote Wellenlinien in Ihrer Startkonfiguration sehen, bewegen Sie den Mauszeiger darüber, um zu erfahren, was das Problem ist, 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: node für den integrierten Node-Debugger, zum Beispiel, oder php und go für die PHP- und Go-Erweiterungen.
• request - der Anforderungstyp dieser Startkonfiguration. Derzeit werden launch und attach unterstützt.
• name - der leserfreundliche Name, der im Dropdown-Menü der Debug-Startkonfiguration angezeigt wird.

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

• presentation - mit den Attributen order, group und hidden im presentation-Objekt können Sie Konfigurationen und Compounds im Dropdown-Menü der Debug-Konfiguration und in der Debug-Schnellauswahl sortieren, gruppieren und ausblenden.
• preLaunchTask - um eine Aufgabe vor dem Start einer Debug-Sitzung auszuführen, setzen Sie dieses Attribut auf das Label einer Aufgabe, die in tasks.json (im .vscode-Ordner des Arbeitsbereichs) angegeben ist. Oder, dies kann auf ${defaultBuildTask} gesetzt werden, um Ihre Standard-Build-Aufgabe zu verwenden.
• postDebugTask - um eine Aufgabe am Ende einer Debug-Sitzung auszuführen, setzen Sie dieses Attribut auf den Namen einer Aufgabe, die in tasks.json (im .vscode-Ordner des Arbeitsbereichs) angegeben ist.
• internalConsoleOptions - dieses Attribut steuert die Sichtbarkeit des Debug-Konsolenfensters während einer Debug-Sitzung.
• debugServer - nur für Debug-Erweiterungsautoren: dieses Attribut ermöglicht es Ihnen, sich mit einem angegebenen Port zu verbinden, anstatt den Debug-Adapter zu starten.
• serverReadyAction - wenn Sie eine URL in einem Webbrowser öffnen möchten, wann immer das zu debuggende Programm eine bestimmte Nachricht an die Debug-Konsole oder das integrierte Terminal ausgibt. Details finden Sie im Abschnitt Automatisch eine URI öffnen, wenn ein Serverprogramm gedebuggt wird unten.

Viele Debugger unterstützen einige der folgenden Attribute

• program - die ausführbare Datei oder die 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 "zu definieren")
• envFile - Pfad zu einer Dotenv-Datei mit Umgebungsvariablen
• cwd - aktuelles Arbeitsverzeichnis für das Finden von Abhängigkeiten und anderen Dateien
• port - Port beim Anhängen an einen laufenden Prozess
• stopOnEntry - sofort anhalten, wenn das Programm gestartet wird
• console - welche Art von Konsole verwendet werden soll, z. B. internalConsole, integratedTerminal oder externalTerminal

Variablensubstitution

VS Code macht häufig verwendete Pfade und andere Werte als Variablen verfügbar und unterstützt Variablensubstitution innerhalb von Zeichenketten in launch.json. Das bedeutet, dass Sie keine absoluten Pfade in Debug-Konfigurationen verwenden müssen. Zum Beispiel gibt ${workspaceFolder} den Stammordner eines Arbeitsbereichsordners an, ${file} die im aktiven Editor geöffnete Datei und ${env:Name} die Umgebungsvariable 'Name'.

Eine vollständige Liste der vordefinierten Variablen finden Sie in der Variablenreferenz oder indem Sie IntelliSense innerhalb der Zeichenkettenattribute von launch.json aufrufen.

{
  "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. an das Programm zu übergebende Argumente), die vom Betriebssystem abhängen, auf dem der Debugger läuft. Tun Sie dies, indem Sie ein plattformspezifisches Literal in die launch.json-Datei einfügen und die entsprechenden Eigenschaften innerhalb dieses Literals angeben.

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

{
  "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 Betriebssystemeigenschaften sind "windows" für Windows, "linux" für Linux und "osx" für macOS. Eigenschaften, die in einem betriebssystemspezifischen Geltungsbereich definiert sind, überschreiben Eigenschaften, die im globalen Geltungsbereich definiert sind.

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

Im folgenden Beispiel wird das Debuggen des Programms immer beim Start gestoppt, 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
      }
    }
  ]
}

Globale Startkonfiguration

Sie können Startkonfigurationen definieren, die in all Ihren Arbeitsbereichen verfügbar sind. Um eine globale Startkonfiguration anzugeben, fügen Sie ein Startkonfigurationsobjekt in Ihre launch-Benutzereinstellung ein. Diese launch-Konfiguration wird dann in Ihren Arbeitsbereichen geteilt. Zum Beispiel

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

Eingabe/Ausgabe zum/vom Debug-Ziel umleiten

Die Umleitung von Ein- und Ausgabe ist Debugger- oder Laufzeitspezifisch, daher hat VS Code keine eingebaute Lösung, die für alle Debugger funktioniert.

Hier sind zwei Ansätze, die Sie in Betracht ziehen möchten

• Starten Sie das zu debuggende Programm ("Debug-Ziel") manuell in einem Terminal oder einer Eingabeaufforderung und leiten Sie die Ein- und Ausgabe nach Bedarf um. Stellen Sie sicher, dass Sie die entsprechenden Befehlszeilenoptionen an das Debug-Ziel übergeben, damit ein Debugger sich daran anhängen kann. Erstellen und führen Sie eine "Anhängen"-Debug-Konfiguration aus, die sich an das Debug-Ziel anhä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 ein Beispiel für eine 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 übergeben wird und unverändert im integrierten Terminal landet.

Verknüpfte Startkonfigurationen

Eine alternative Methode zum Starten mehrerer Debug-Sitzungen ist die Verwendung einer verknüpften Startkonfiguration. Sie können verknüpfte Startkonfigurationen in der compounds-Eigenschaft 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 vor dem Start der einzelnen Debug-Sitzungen ausgeführt wird. Das boolesche Flag stopAll steuert, ob das manuelle Beenden einer Sitzung alle Verbundsitzungen 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
    }
  ]
}

Verknüpfte Startkonfigurationen werden auch im Dropdown-Menü der Startkonfiguration angezeigt.

Automatisch eine URI öffnen, wenn ein Serverprogramm gedebuggt wird

Die Entwicklung eines Webprogramms erfordert normalerweise das Öffnen einer bestimmten URL in einem Webbrowser, um den Servercode 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 über Port 3000 zu lauschen. Der Port wird in der Debug-Konsole angekündigt, und typischerweise würde der Entwickler nun https://:3000 in seine Browseranwendung eingeben.

Die Funktion serverReadyAction ermöglicht es, 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 Eigenschaft pattern den regulären Ausdruck zum Abgleichen der Ausgabezeichenfolge des Programms, die den Port ankündigt. Das Muster für die Portnummer wird in Klammern gesetzt, damit es als Erfassungsgruppe eines regulären Ausdrucks verfügbar ist. In diesem Beispiel extrahieren wir nur die Portnummer, aber es ist auch möglich, eine vollständige URI zu extrahieren.

Die Eigenschaft uriFormat beschreibt, wie die Portnummer in eine URI umgewandelt wird. Das erste %s wird durch die erste Erfassungsgruppe des passenden Musters substituiert.

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

Debugging über Microsoft Edge oder Chrome auslösen

Alternativ kann 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 die gängigen Meldungen "listening on port 3000" oder "Now listening on: https://:5001" abgleicht.
• 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 anderen Debugger verwenden. Dies können Sie tun, indem Sie action auf startDebugging setzen und eine name-Eigenschaft auf den Namen der Startkonfiguration setzen, die gestartet werden soll, wenn das pattern abgeglichen wird.

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

Hier die Funktion serverReadyAction in Aktion

Nächste Schritte

• Aufgaben - Beschreibt, wie Aufgaben mit Gulp, Grunt und Jake ausgeführt 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-Menü von Ausführen und Debuggen. Was ist falsch?

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