Variablenreferenz

Visual Studio Code unterstützt die Variablensubstitution in den Konfigurationsdateien für Debugging und Tasks sowie für einige ausgewählte Einstellungen. Die Variablensubstitution wird innerhalb einiger Schlüssel- und Wertstrings in den Dateien launch.json und tasks.json unter Verwendung der Syntax ${variablenName} unterstützt.

Vordefinierte Variablen

Die folgenden vordefinierten Variablen werden unterstützt

Beispiel für vordefinierte Variablen

Angenommen, Sie haben die folgenden Bedingungen

1. Eine Datei unter /home/benutzername/projektordner/ordner/datei.ext ist in Ihrem Editor geöffnet;
2. Das Verzeichnis /home/benutzername/projektordner ist als Ihr Stammverzeichnis geöffnet.

Dies führt zu den folgenden Werten für jede der Variablen

• ${userHome}: /home/benutzername
• ${workspaceFolder}: /home/benutzername/projektordner
• ${workspaceFolderBasename}: projektordner
• ${file}: /home/benutzername/projektordner/ordner/datei.ext
• ${fileWorkspaceFolder}: /home/benutzername/projektordner
• ${relativeFile}: ordner/datei.ext
• ${relativeFileDirname}: ordner
• ${fileBasename}: datei.ext
• ${fileBasenameNoExtension}: datei
• ${fileExtname}: .ext
• ${fileDirname}: /home/benutzername/projektordner/ordner
• ${fileDirnameBasename}: ordner
• ${lineNumber}: Zeilennummer des Cursors
• ${columnNumber}: Spaltennummer des Cursors
• ${selectedText}: im Code-Editor ausgewählter Text
• ${execPath}: Speicherort von Code.exe
• ${pathSeparator}: / unter macOS oder Linux, \ unter Windows

Nach Workspace-Ordnern abgegrenzte Variablen

Durch Anhängen des Namens des Stammordners an eine Variable (getrennt durch einen Doppelpunkt) ist es möglich, auf Geschwister-Stammordner eines Arbeitsbereichs zuzugreifen. Ohne den Namen des Stammordners ist die Variable auf denselben Ordner beschränkt, in dem sie verwendet wird.

Zum Beispiel bezieht sich in einem Multi-Root-Workspace mit den Ordnern Server und Client ein ${workspaceFolder:Client} auf den Pfad des Client-Roots.

Umgebungsvariablen

Sie können Umgebungsvariablen mit der Syntax ${env:Name} referenzieren. Zum Beispiel referenziert ${env:USERNAME} die Umgebungsvariable USERNAME.

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

Konfigurationsvariablen

Um VS Code-Einstellungen (Konfigurationen) zu referenzieren, verwenden Sie die Syntax ${config:Name}. Zum Beispiel referenziert ${config:editor.fontSize} die Einstellung editor.fontSize.

Befehlsvariablen

Sie können jeden VS Code-Befehl als Variable mit der Syntax ${command:commandID} verwenden.

Eine Befehlsvariable wird durch das (Zeichenfolgen-)Ergebnis der Befehlsauswertung ersetzt. Die Implementierung eines Befehls kann von einer einfachen Berechnung ohne Benutzeroberfläche bis hin zu komplexer Funktionalität reichen, die auf den über die VS Code Extension API verfügbaren UI-Funktionen basiert. Wenn der Befehl etwas anderes als eine Zeichenfolge zurückgibt, wird die Variablensubstitution nicht abgeschlossen. Befehlsvariablen müssen eine Zeichenfolge zurückgeben.

Ein Beispiel für diese Funktionalität ist die Node.js-Debuggererweiterung von VS Code, die einen interaktiven Befehl extension.pickNodeProcess bereitstellt, um einen einzelnen Prozess aus der Liste aller laufenden Node.js-Prozesse auszuwählen. Der Befehl gibt die Prozess-ID des ausgewählten Prozesses zurück. Dies ermöglicht die Verwendung des Befehls extension.pickNodeProcess in einer Attach by Process ID-Startkonfiguration wie folgt

{
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach by Process ID",
      "processId": "${command:extension.pickNodeProcess}"
    }
  ]
}

Bei Verwendung einer Befehlsvariablen in einer launch.json-Konfiguration wird die umgebende launch.json-Konfiguration als Objekt über ein Argument an den Befehl übergeben. Dies ermöglicht es Befehlen, den Kontext und die Parameter der spezifischen launch.json-Konfiguration zu kennen, wenn sie aufgerufen werden.

Eingabevariablen

Befehlsvariablen sind bereits leistungsstark, ihnen fehlt jedoch ein Mechanismus zur Konfiguration des auszuführenden Befehls für einen bestimmten Anwendungsfall. Beispielsweise ist es nicht möglich, eine Eingabeaufforderungsnachricht oder einen Standardwert an eine generische "Benutzereingabeaufforderung" zu übergeben.

Diese Einschränkung wird durch Eingabevariablen gelöst, die die Syntax ${input:variableID} haben. Die variableID bezieht sich auf Einträge im inputs-Abschnitt von launch.json und tasks.json, in denen zusätzliche Konfigurationsattribute angegeben sind. Verschachtelung von Eingabevariablen wird nicht unterstützt.

Das folgende Beispiel zeigt die Gesamtstruktur einer tasks.json, die Eingabevariablen verwendet

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "task name",
      "command": "${input:variableID}"
      // ...
    }
  ],
  "inputs": [
    {
      "id": "variableID",
      "type": "type of input variable"
      // type specific configuration attributes
    }
  ]
}

Derzeit unterstützt VS Code drei Arten von Eingabevariablen

• promptString: zeigt ein Eingabefeld an, um eine Zeichenfolge vom Benutzer zu erhalten.
• pickString: zeigt ein Quick Pick Dropdown an, damit der Benutzer aus mehreren Optionen auswählen kann.
• command: führt einen beliebigen Befehl aus.

Jeder Typ erfordert zusätzliche Konfigurationsattribute

promptString:

• description: wird in der Schnelleingabe angezeigt und liefert Kontext für die Eingabe.
• default: Standardwert, der verwendet wird, wenn der Benutzer nichts anderes eingibt.
• password: auf true gesetzt, um die Eingabe mit einer Passwortabfrage durchzuführen, die den eingegebenen Wert nicht anzeigt.

pickString:

• description: wird in der Schnellauswahl angezeigt und liefert Kontext für die Eingabe.
• options: ein Array von Optionen, aus denen der Benutzer auswählen kann.
• default: Standardwert, der verwendet wird, wenn der Benutzer nichts anderes eingibt. Er muss einer der Optionswerte sein.

Eine Option kann ein Zeichenfolgenwert oder ein Objekt mit sowohl einer Bezeichnung als auch einem Wert sein. Das Dropdown zeigt Bezeichnung: Wert an.

command:

• command: führt einen Befehl bei der Variablensubstitution aus.
• args: optionales Options-Bag, das an die Implementierung des Befehls übergeben wird.

Unten finden Sie ein Beispiel für eine tasks.json, die die Verwendung von inputs unter Verwendung der Angular CLI veranschaulicht

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "ng g",
      "type": "shell",
      "command": "ng",
      "args": ["g", "${input:componentType}", "${input:componentName}"]
    }
  ],
  "inputs": [
    {
      "type": "pickString",
      "id": "componentType",
      "description": "What type of component do you want to create?",
      "options": [
        "component",
        "directive",
        "pipe",
        "service",
        "class",
        "guard",
        "interface",
        "enum"
      ],
      "default": "component"
    },
    {
      "type": "promptString",
      "id": "componentName",
      "description": "Name your component.",
      "default": "my-new-component"
    }
  ]
}

Ausführen des Beispiels

Das folgende Beispiel zeigt, wie eine Benutzereingabevariable vom Typ command in einer Debug-Konfiguration verwendet wird, die es dem Benutzer ermöglicht, einen Testfall aus einer Liste aller Testfälle in einem bestimmten Ordner auszuwählen. Es wird davon ausgegangen, dass eine Erweiterung einen Befehl extension.mochaSupport.testPicker bereitstellt, der alle Testfälle an einem konfigurierbaren Ort findet und eine Auswahl-UI anzeigt, um einen davon auszuwählen. Die Argumente für eine Befehlseingabe werden durch den Befehl selbst definiert.

{
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Run specific test",
      "program": "${workspaceFolder}/${input:pickTest}"
    }
  ],
  "inputs": [
    {
      "id": "pickTest",
      "type": "command",
      "command": "extension.mochaSupport.testPicker",
      "args": {
        "testFolder": "/out/tests"
      }
    }
  ]
}

Befehlseingaben können auch mit Aufgaben verwendet werden. In diesem Beispiel wird der integrierte Befehl "Terminate Task" verwendet. Er kann ein Argument zum Beenden aller Aufgaben akzeptieren.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Terminate All Tasks",
      "command": "echo ${input:terminate}",
      "type": "shell",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "terminate",
      "type": "command",
      "command": "workbench.action.tasks.terminate",
      "args": "terminateAll"
    }
  ]
}

Häufig gestellte Fragen

Details zur Variablensubstitution in einer Debug-Konfiguration oder einem Task

Die Variablensubstitution in Debug-Konfigurationen oder Tasks ist ein zweistufiger Prozess

• Im ersten Schritt werden alle Variablen zu Zeichenfolgenergebnissen ausgewertet. Wenn eine Variable mehr als einmal vorkommt, wird sie nur einmal ausgewertet.
• Im zweiten Schritt werden alle Variablen durch die Ergebnisse aus dem ersten Schritt ersetzt.

Eine Folge davon ist, dass die Auswertung einer Variable (z. B. einer auf einer Erweiterung basierenden Befehlsvariable) keinen Zugriff auf andere substituierte Variablen in der Debug-Konfiguration oder dem Task hat. Sie sieht nur die ursprünglichen Variablen. Das bedeutet, dass Variablen nicht voneinander abhängig sein können (was die Isolation sicherstellt und die Substitution robust gegenüber der Auswertungsreihenfolge macht).

Wird die Variablensubstitution in Benutzer- und Workspace-Einstellungen unterstützt?

Die vordefinierten Variablen werden in einer Auswahl von Einstellungsschlüsseln in settings.json-Dateien unterstützt, wie z. B. die Werte für cwd, env, shell und shellArgs im Terminal. Einige Einstellungen, wie z. B. window.title, haben ihre eigenen Variablen

  "window.title": "${dirty}${activeEditorShort}${separator}${rootName}${separator}${appName}"

Beziehen Sie sich auf die Kommentare im Einstellungs-Editor (⌘, (Windows, Linux Ctrl+,)), um sich über einstellungsspezifische Variablen zu informieren.

Warum ist ${workspaceRoot} nicht dokumentiert?

Die Variable ${workspaceRoot} wurde zugunsten von ${workspaceFolder} als veraltet markiert, um besser mit der Unterstützung für Multi-Root Workspaces übereinzustimmen.

Warum werden Variablen in tasks.json nicht aufgelöst?

Nicht alle Werte in tasks.json unterstützen die Variablensubstitution. Insbesondere unterstützen nur command, args und options die Variablensubstitution. Eingabevariablen im Abschnitt inputs werden nicht aufgelöst, da die Verschachtelung von Eingabevariablen nicht unterstützt wird.

Woher weiß ich den tatsächlichen Wert einer Variable?

Ein einfacher Weg, den Laufzeitwert einer Variable zu überprüfen, ist die Erstellung eines VS Code Tasks, um den Variablenwert in der Konsole auszugeben. Um beispielsweise den aufgelösten Wert für ${workspaceFolder} anzuzeigen, können Sie die folgende einfache "echo"-Aufgabe in tasks.json erstellen und ausführen (Terminal > Task ausführen)

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "echo",
      "type": "shell",
      "command": "echo ${workspaceFolder}"
    }
  ]
}

Verwandte Ressourcen

• Debugging
• Aufgaben