仮想ワークスペース

Name: Visual Studio Code
Author: Microsoft

GitHub Repositories 拡張機能のような拡張機能は、ファイルシステムプロバイダーによってバックアップされた 1 つまたは複数のフォルダーで VS Code を開きます。拡張機能がファイルシステムプロバイダーを実装する場合、ワークスペースリソースはローカルディスク上にはなく、サーバーまたはクラウド上にある仮想リソースである可能性があり、編集操作はそこで行われます。

この構成は、仮想ワークスペースと呼ばれます。仮想ワークスペースが VS Code ウィンドウで開かれている場合、他のリモート開発ウィンドウと同様に、左下隅のリモートインジケーターにラベルが表示されます。

Remote indicator

すべての拡張機能が仮想リソースで動作できるわけではなく、リソースがディスク上にある必要がある場合があります。一部の拡張機能は、ディスクアクセスに依存するツールを使用したり、同期ファイルアクセスを必要としたり、必要なファイルシステム抽象化がなかったりします。これらの場合、仮想ワークスペースでは、VS Code は制限モードで実行されていること、および一部の拡張機能が非アクティブ化されているか、機能が制限されていることをユーザーに示します。

一般に、ユーザーはできるだけ多くの拡張機能が仮想ワークスペースで動作し、リモートリソースの参照と編集時に良好なユーザーエクスペリエンスを得ることを望んでいます。このガイドでは、拡張機能が仮想ワークスペースに対してテストする方法、仮想ワークスペースで動作できるようにするための変更について説明し、virtualWorkspaces 機能プロパティを紹介します。

仮想ワークスペースで動作するように拡張機能を変更することは、VS Code for the Web でうまく動作するためにも重要なステップです。VS Code for the Web はブラウザー内で完全に実行され、ワークスペースはブラウザーサンドボックスのために仮想化されています。詳細については、Web 拡張機能ガイドを参照してください。

自分の拡張機能は影響を受けますか?

拡張機能に実行可能コードがなく、テーマ、キーバインド、スニペット、または文法拡張機能のような純粋に宣言的なものである場合、仮想ワークスペースで実行でき、変更は必要ありません。

コードを含む拡張機能、つまり main エントリーポイントを定義する拡張機能は、検査と、場合によっては変更が必要です。

仮想ワークスペースに対して拡張機能を実行する

GitHub Repositories 拡張機能をインストールし、コマンドパレットから GitHub リポジトリを開く... コマンドを実行します。コマンドはクイックピックスドロップダウンを表示し、任意の GitHub URL を貼り付けるか、特定のリポジトリまたはプルリクエストを検索するように選択できます。

これにより、すべてのリソースが仮想である仮想ワークスペースの VS Code ウィンドウが開きます。

拡張機能コードが仮想リソースに対応しているか確認する

仮想ファイルシステムの VS Code API サポートは、かなり前から存在しています。ファイルシステムプロバイダー API を確認できます。

ファイルシステムプロバイダーは、新しい URI スキーム (たとえば、vscode-vfs) に対して登録され、そのファイルシステム上のリソースは、そのスキーマを使用する URI (vscode-vfs://github/microsoft/vscode/package.json) によって表されます。

拡張機能が VS Code API から返された URI をどのように処理するかを確認してください

URI スキームが file であると決して想定しないでください。URI.fsPath は、URI スキームが file の場合にのみ使用できます。
ファイルシステム操作のための fs node モジュールの使用法に注意してください。可能であれば、適切なファイルシステムプロバイダーに委譲する vscode.workspace.fs API を使用してください。
fs アクセスに依存するサードパーティコンポーネント (たとえば、言語サーバーまたは node モジュール) を確認してください。
コマンドから実行可能ファイルとタスクを実行する場合は、これらのコマンドが仮想ワークスペースウィンドウで意味があるかどうか、または無効にする必要があるかどうかを確認してください。

拡張機能が仮想ワークスペースを処理できるかどうかを通知する

package.json の capabilities の下の virtualWorkspaces プロパティは、拡張機能が仮想ワークスペースで動作するかどうかを通知するために使用されます。

仮想ワークスペースのサポートなし

以下の例は、拡張機能が仮想ワークスペースをサポートしておらず、この設定で VS Code によって有効にされるべきではないことを宣言しています。

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": false,
      "description": "Debugging is not possible in virtual workspaces."
    }
  }
}

仮想ワークスペースの部分的および完全なサポート

拡張機能が仮想ワークスペースで動作するか、部分的に動作する場合は、"virtualWorkspaces": true を定義する必要があります。

{
  "capabilities": {
    "virtualWorkspaces": true
  }
}

拡張機能が動作するが、機能が制限されている場合は、ユーザーに制限事項を説明する必要があります

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": "limited",
      "description": "In virtual workspaces, resolving and finding references across files is not supported."
    }
  }
}

説明は拡張機能ビューに表示されます

Extensions view

拡張機能は、以下で説明するように、仮想ワークスペースでサポートされていない機能を無効にする必要があります。

デフォルト

"virtualWorkspaces": true は、virtualWorkspaces 機能をまだ入力していないすべての拡張機能のデフォルトです。

ただし、仮想ワークスペースをテストしている間に、仮想ワークスペースで無効にする必要があると思われる拡張機能のリストを作成しました。リストは issue #122836 にあります。これらの拡張機能は、デフォルトで "virtualWorkspaces": false を持っています。

もちろん、拡張機能の作成者は、この決定を下すのに適した立場にあります。拡張機能の package.json の virtualWorkspaces 機能は、当社のデフォルトをオーバーライドし、最終的には当社のリストを廃止する予定です。

仮想ワークスペースが開かれたときに機能を無効にする

コマンドとビューのコントリビューションを無効にする

コマンドとビュー、および他の多くのコントリビューションの可用性は、when 句のコンテキストキーを通じて制御できます。

virtualWorkspace コンテキストキーは、すべてのワークスペースフォルダーが仮想ファイルシステム上にある場合に設定されます。以下の例では、仮想ワークスペースにない場合にのみ、コマンドパレットにコマンド npm.publish が表示されます

{
  "menus": {
    "commandPalette": [
      {
        "command": "npm.publish",
        "when": "!virtualWorkspace"
      }
    ]
  }
}

resourceScheme コンテキストキーは、ファイルエクスプローラーで現在選択されている要素、またはエディターで開いている要素の URI スキームに設定されます。

以下の例では、基になるリソースがローカルディスク上にある場合にのみ、npm.runSelectedScript コマンドがエディターコンテキストメニューに表示されます。

{
  "menus": {
    "editor/context": [
      {
        "command": "npm.runSelectedScript",
        "when": "resourceFilename == 'package.json' && resourceScheme == file"
      }
    ]
  }
}

プログラムで仮想ワークスペースを検出する

現在のワークスペースが file スキーム以外で構成され、仮想であるかどうかを確認するには、次のソースコードを使用できます

const isVirtualWorkspace =
  workspace.workspaceFolders &&
  workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');

言語拡張機能と仮想ワークスペース

仮想ワークスペースでの言語サポートに対する期待は何ですか?

すべての拡張機能が仮想リソースで完全に動作できるわけではないのは現実的ではありません。多くの拡張機能は、同期ファイルアクセスとディスク上のファイルを必要とする外部ツールを使用しています。したがって、以下に示すように、Basic および Single-file サポートなどの制限された機能のみを提供しても問題ありません。

A. Basic 言語サポート

TextMate トークン化と色付け
言語固有の編集サポート: 括弧のペア、コメント、Enter キーの規則、折りたたみマーカー
コードスニペット

B. Single-file 言語サポート

ドキュメントシンボル (アウトライン)、折りたたみ、選択範囲
ドキュメントのハイライト、セマンティックハイライト、ドキュメントの色
補完、ホバー、署名ヘルプ、現在のファイルおよび静的言語ライブラリのシンボルに基づく参照/宣言の検索
フォーマット、リンクされた編集
構文検証、および同じファイルのセマンティック検証とコードアクション

C. クロスファイル、ワークスペース対応 言語サポート

ファイル間の参照
ワークスペースシンボル
ワークスペース/プロジェクト内のすべてのファイルの検証

VS Code に付属している豊富な言語拡張機能 (TypeScript、JSON、CSS、HTML、Markdown) は、仮想リソースで作業する場合、シングルファイル言語サポートに限定されています。

言語拡張機能を無効にする

単一のファイルでの作業がオプションでない場合、言語拡張機能は仮想ワークスペースにあるときに拡張機能を無効にすることも決定できます。

拡張機能が文法と無効にする必要のある豊富な言語サポートの両方を提供する場合、文法も無効になります。これを回避するには、基本的な言語拡張機能 (文法、言語構成、スニペット) を豊富な言語サポートとは別に作成し、2 つの拡張機能を持つことができます。

基本的な言語拡張機能は "virtualWorkspaces": true を持ち、言語 ID、構成、文法、およびスニペットを提供します。
豊富な言語拡張機能は "virtualWorkspaces": false を持ち、main ファイルを含みます。言語サポート、コマンドを提供し、基本的な言語拡張機能への拡張機能の依存関係 (extensionDependencies) を持ちます。豊富な言語拡張機能は、確立された拡張機能の拡張機能 ID を保持する必要があります。これにより、ユーザーは単一の拡張機能をインストールすることで完全な機能を継続して利用できます。

このアプローチは、JSON 拡張機能と JSON 言語機能拡張機能で構成される JSON などの組み込み言語拡張機能で見ることができます。

この分離は、信頼されていないワークスペースが制限付きモードで実行されている場合にも役立ちます。豊富な言語拡張機能は多くの場合、信頼が必要ですが、基本的な言語機能は任意の設定で実行できます。

言語セレクター

言語機能 (たとえば、補完、ホバー、コードアクションなど) のプロバイダーを登録する場合は、プロバイダーがサポートするスキームを必ず指定してください

return vscode.languages.registerCompletionItemProvider(
  { language: 'typescript', scheme: 'file' },
  {
    provideCompletionItems(document, position, token) {
      // ...
    }
  }
);

仮想リソースにアクセスするための言語サーバープロトコル (LSP) のサポートはどうですか?

ファイルシステムプロバイダーのサポートを LSP に追加する作業が進行中です。言語サーバープロトコルの issue #1264 で追跡されています。

04/03/2025