変数リファレンス

Visual Studio Code は、デバッグおよびタスクの構成ファイル、および一部の特定の設定において変数置換をサポートしています。変数置換は、${variableName} 構文を使用することで、launch.json および tasks.json ファイル内の一部のキーおよび値の文字列内でサポートされています。

定義済み変数

以下の定義済み変数がサポートされています

定義済み変数の例

以下の条件を想定します

1. エディタで /home/your-username/your-project/folder/file.ext にあるファイルが開かれている
2. ルートワークスペースとして /home/your-username/your-project ディレクトリが開かれている

この場合、各変数は以下の値になります

• ${userHome}: /home/your-username
• ${workspaceFolder}: /home/your-username/your-project
• ${workspaceFolderBasename}: your-project
• ${file}: /home/your-username/your-project/folder/file.ext
• ${fileWorkspaceFolder}: /home/your-username/your-project
• ${relativeFile}: folder/file.ext
• ${relativeFileDirname}: folder
• ${fileBasename}: file.ext
• ${fileBasenameNoExtension}: file
• ${fileExtname}: .ext
• ${fileDirname}: /home/your-username/your-project/folder
• ${fileDirnameBasename}: folder
• ${lineNumber}: カーソルの行番号
• ${columnNumber}: カーソルの列番号
• ${selectedText}: コードエディタで選択されたテキスト
• ${execPath}: Code.exe の場所
• ${pathSeparator}: macOS または Linux では /、Windows では \

プラットフォームおよびワークスペースに関する考慮事項

プラットフォーム固有の動作

一部の定義済み変数は、オペレーティングシステムによって解決結果が異なる場合があります

• Windows では、ファイルパスにバックスラッシュ（\）を使用します。tasks.json や launch.json などの JSON ファイルでパスを作成する際は、バックスラッシュが正しくエスケープされていることを確認してください（例: "${workspaceFolder}\\subdir"）。
• macOS および Linux では、ファイルパスにフォワードスラッシュ（/）を使用します。

プラットフォーム間で構成を移植可能にするために、${pathSeparator} または ${/} を使用することを推奨します。

ワークスペースフォルダーごとの変数スコープ

変数にルートフォルダー名を（コロンで区切って）追加することで、ワークスペースの兄弟ルートフォルダーを参照することが可能です。ルートフォルダー名を指定しない場合、その変数は使用されているフォルダーに対してスコープされます。

例えば、Server と Client というフォルダーを持つマルチルートワークスペースにおいて、${workspaceFolder:Client} は Client ルートのパスを参照します。

環境変数

${env:Name} 構文を使用して環境変数を参照できます。例えば、${env:USERNAME} は USERNAME 環境変数を参照します。

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

設定変数

VS Code の設定（configurations）を参照するには、${config:Name} 構文を使用します。例えば、${config:editor.fontSize} は editor.fontSize 設定を参照します。

コマンド変数

${command:commandID} 構文を使用して、任意の VS Code コマンドを変数として使用できます。

コマンド変数は、コマンドの評価結果（文字列）に置き換えられます。コマンドの実装は、UI を伴わない単純な計算から、VS Code の拡張機能 API を通じて利用可能な UI 機能に基づいた高度な機能まで多岐にわたります。コマンドが文字列以外の値を返した場合、変数置換は完了しません。コマンド変数は必ず文字列を返す必要があります。

この機能の例として、VS Code の Node.js デバッガー拡張機能があります。これは、実行中のすべての Node.js プロセスの一覧から単一のプロセスを選択するための対話型コマンド extension.pickNodeProcess を提供します。このコマンドは、選択されたプロセスのプロセス ID を返します。これにより、プロセス ID によるアタッチの起動構成で以下のように extension.pickNodeProcess コマンドを使用できるようになります。

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

launch.json 構成でコマンド変数を使用する場合、対象の launch.json 構成が引数としてコマンドにオブジェクト形式で渡されます。これにより、呼び出されたコマンド側で特定の launch.json 構成のコンテキストやパラメーターを把握できます。

入力変数

コマンド変数は非常に強力ですが、特定のユースケースで実行するコマンドを構成するメカニズムが不足しています。例えば、汎用的な「ユーザー入力プロンプト」に対してプロンプトメッセージやデフォルト値を渡すことはできません。

この制限は、入力変数によって解決されます。構文は ${input:variableID} です。variableID は launch.json および tasks.json の inputs セクションのエントリを参照し、そこで追加の構成属性が指定されます。入力変数のネストはサポートされていません。

以下の例は、入力変数を使用した tasks.json の全体構造を示しています。

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

現在、VS Code は 3 種類の入力変数をサポートしています。

• promptString: 入力ボックスを表示し、ユーザーから文字列を取得します。
• pickString: Quick Pick ドロップダウンを表示し、ユーザーが複数のオプションから選択できるようにします。
• command: 任意のコマンドを実行します。

各タイプには、追加の構成属性が必要です。

promptString:

• description: クイック入力に表示され、入力のコンテキストを提供します。
• default: ユーザーが何も入力しなかった場合に使用されるデフォルト値。
• password: true に設定すると、入力値が表示されないパスワードプロンプトになります。

pickString:

• description: クイック選択に表示され、入力のコンテキストを提供します。
• options: ユーザーが選択するためのオプションの配列。
• default: ユーザーが何も入力しなかった場合に使用されるデフォルト値。オプション値のいずれかである必要があります。

オプションは文字列値、または label と value の両方を持つオブジェクトのいずれかです。ドロップダウンには label: value が表示されます。

command:

• command: 変数展開時にコマンドを実行します。
• args: コマンドの実装に渡されるオプションの引数バッグ。

以下は、Angular CLI を使用して inputs を利用した tasks.json の例です。

{
  "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"
    }
  ]
}

例の実行

以下の例は、デバッグ構成でタイプ command のユーザー入力変数を使用する方法を示しています。ユーザーは特定のフォルダー内にあるすべてのテストケースの一覧からテストケースを選択できます。ある拡張機能が extension.mochaSupport.testPicker コマンドを提供しており、それが構成可能な場所にあるすべてのテストケースを特定し、選択するための UI を表示すると仮定します。コマンド入力の引数は、コマンド自体によって定義されます。

{
  "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"
      }
    }
  ]
}

コマンド入力はタスクでも使用できます。この例では、組み込みの「Terminate Task（タスクの終了）」コマンドを使用しています。これは引数を受け取り、すべてのタスクを終了させることができます。

{
  "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"
    }
  ]
}

よくある質問

デバッグ構成またはタスクにおける変数置換の詳細

デバッグ構成またはタスクにおける変数置換は、2 パス（2 段階）のプロセスです。

• 第 1 パスでは、すべての変数が文字列結果に評価されます。同じ変数が複数回出現する場合、評価は一度だけ行われます。
• 第 2 パスでは、すべての変数が第 1 パスの結果で置換されます。

この結果、変数の評価（例：拡張機能で実装されたコマンドベースの変数）は、デバッグ構成やタスク内の他の置換済み変数にアクセスできません。評価時に見えるのは元の変数のみです。つまり、変数は互いに依存することができません（これにより分離が保証され、評価順序に関わらず置換が堅牢になります）。

ユーザー設定およびワークスペース設定で変数置換はサポートされていますか？

定義済み変数は、settings.json ファイル内のターミナルの cwd、env、shell、shellArgs 値など、一部の設定キーでサポートされています。 window.title VS Code で開く VS Code Insiders で開く のような一部の設定には、独自の変数が用意されています。

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

設定固有の変数については、設定エディター（⌘, (Windows, Linux Ctrl+,)）内のコメントを参照してください。

${workspaceRoot} がドキュメントに記載されていないのはなぜですか？

変数 ${workspaceRoot} は、マルチルートワークスペースのサポートとの整合性を高めるために、${workspaceFolder} に置き換えられ非推奨となりました。

tasks.json 内の変数が解決されないのはなぜですか？

tasks.json 内のすべての値が変数置換をサポートしているわけではありません。具体的には、command、args、options のみが変数置換をサポートしています。inputs セクションの入力変数は、入力変数のネストがサポートされていないため解決されません。

変数の実際の値を知るにはどうすればよいですか？

変数の実行時の値を確認する簡単な方法は、VS Code のタスクを作成し、変数の値をコンソールに出力することです。例えば、${workspaceFolder} の解決された値を確認するには、tasks.json に以下の単純な「echo」タスクを作成して実行（ターミナル > タスクの実行）します。

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

関連リソース

• デバッグ
• タスク