タスクプロバイダー

通常、ユーザーはVisual Studio Codeでタスクをtasks.jsonファイルに定義します。しかし、ソフトウェア開発中には、VS Code拡張機能がタスクプロバイダーを使用して自動的に検出できるタスクがいくつかあります。VS Codeからタスク：タスクの実行コマンドが実行されると、すべてのアクティブなタスクプロバイダーが、ユーザーが実行できるタスクを提供します。tasks.jsonファイルでは、ユーザーが特定のフォルダーやワークスペースのタスクを手動で定義できますが、タスクプロバイダーはワークスペースに関する詳細を検出し、対応するVS Codeタスクを自動的に作成できます。たとえば、タスクプロバイダーはmakeやRakefileのような特定のビルドファイルがあるかどうかを確認し、ビルドタスクを作成できます。このトピックでは、拡張機能がエンドユーザーにタスクを自動検出し、提供する方法について説明します。

このガイドでは、Rakefileで定義されたタスクを自動検出するタスクプロバイダーを構築する方法を説明します。完全なソースコードは次の場所にあります：https://github.com/microsoft/vscode-extension-samples/tree/main/task-provider-sample。

タスク定義

システム内でタスクを一意に識別するために、タスクを提供する拡張機能は、タスクを識別するプロパティを定義する必要があります。Rakeの例では、タスク定義は次のようになります。

"taskDefinitions": [
    {
        "type": "rake",
        "required": [
            "task"
        ],
        "properties": {
            "task": {
                "type": "string",
                "description": "The Rake task to customize"
            },
            "file": {
                "type": "string",
                "description": "The Rake file that provides the task. Can be omitted."
            }
        }
    }
]

これはrakeタスクのタスク定義を提供します。タスク定義にはtaskとfileの2つの属性があります。taskはRakeタスクの名前で、fileはタスクを含むRakefileを指します。taskプロパティは必須で、fileプロパティはオプションです。file属性が省略された場合、ワークスペースフォルダーのルートにあるRakefileが使用されます。

When句

タスク定義には、オプションでwhenプロパティを含めることができます。whenプロパティは、このタイプのタスクが利用可能になる条件を指定します。whenプロパティは、whenプロパティが存在するVS Codeの他の場所と同じように機能します。タスク定義を作成する際には、次のコンテキストを常に考慮する必要があります。

• shellExecutionSupported: VS Codeがデスクトップアプリケーションとして実行されている場合、またはDev Containersのようなリモート拡張機能を使用している場合など、VS CodeがShellExecutionタスクを実行できるときにTrueになります。
• processExecutionSupported: VS Codeがデスクトップアプリケーションとして実行されている場合、またはDev Containersのようなリモート拡張機能を使用している場合など、VS CodeがProcessExecutionタスクを実行できるときにTrueになります。現在、これは常にshellExecutionSupportedと同じ値になります。
• customExecutionSupported: VS CodeがCustomExecutionを実行できるときにTrueになります。これは常にTrueです。

タスクプロバイダー

拡張機能がコード補完をサポートできるようにする言語プロバイダーと同様に、拡張機能はタスクプロバイダーを登録して、利用可能なすべてのタスクを計算できます。これは、次のコードスニペットに示すように、vscode.tasks名前空間を使用して行われます。

import * as vscode from 'vscode';

let rakePromise: Thenable<vscode.Task[]> | undefined = undefined;
const taskProvider = vscode.tasks.registerTaskProvider('rake', {
  provideTasks: () => {
    if (!rakePromise) {
      rakePromise = getRakeTasks();
    }
    return rakePromise;
  },
  resolveTask(_task: vscode.Task): vscode.Task | undefined {
    const task = _task.definition.task;
    // A Rake task consists of a task and an optional file as specified in RakeTaskDefinition
    // Make sure that this looks like a Rake task by checking that there is a task.
    if (task) {
      // resolveTask requires that the same definition object be used.
      const definition: RakeTaskDefinition = <any>_task.definition;
      return new vscode.Task(
        definition,
        _task.scope ?? vscode.TaskScope.Workspace,
        definition.task,
        'rake',
        new vscode.ShellExecution(`rake ${definition.task}`)
      );
    }
    return undefined;
  }
});

provideTasksと同様に、resolveTaskメソッドはVS Codeによって拡張機能からタスクを取得するために呼び出されます。resolveTaskはprovideTasksの代わりに呼び出すことができ、それを実装するプロバイダーのオプションのパフォーマンス向上を目的としています。たとえば、ユーザーが拡張機能によって提供されるタスクを実行するキーバインディングを持っている場合、VS Codeはそのタスクプロバイダーに対してresolveTaskを呼び出し、すべてのタスクを提供するためにprovideTasksを呼び出して待つのではなく、そのタスクをすばやく取得する方が良いでしょう。ユーザーが個々のタスクプロバイダーをオフにできる設定を持つことは良い習慣であり、これは一般的です。ユーザーは、特定のプロバイダーからのタスクの取得が遅いことに気づき、そのプロバイダーをオフにするかもしれません。この場合でも、ユーザーはtasks.jsonでこのプロバイダーからのタスクの一部を参照している可能性があります。resolveTaskが実装されていない場合、tasks.json内のタスクが作成されなかったという警告が表示されます。resolveTaskを使用すると、拡張機能はtasks.jsonで定義されたタスクに対してタスクを提供できます。

getRakeTasksの実装は次のことを行います。

• 各ワークスペースフォルダーでrake -AT -f Rakefileコマンドを使用して、Rakefileに定義されているすべてのrakeタスクを一覧表示します。
• stdio出力を解析します。
• リストされたすべてのタスクについて、vscode.Taskの実装を作成します。

Rakeタスクのインスタンス化には、package.jsonファイルで定義されたタスク定義が必要なため、VS CodeはTypeScriptインターフェースを使用して構造も次のように定義します。

interface RakeTaskDefinition extends vscode.TaskDefinition {
  /**
   * The task name
   */
  task: string;

  /**
   * The rake file containing the task
   */
  file?: string;
}

最初のワークスペースフォルダーのcompileというタスクから出力が来ると仮定すると、対応するタスクの作成は次のようになります。

let task = new vscode.Task(
  { type: 'rake', task: 'compile' },
  vscode.workspace.workspaceFolders[0],
  'compile',
  'rake',
  new vscode.ShellExecution('rake compile')
);

出力にリストされているすべてのタスクについて、上記のパターンを使用して対応するVS Codeタスクが作成され、getRakeTasks呼び出しからすべてのタスクの配列が返されます。

ShellExecutionは、OS固有のシェルでrake compileコマンドを実行します（たとえば、WindowsではPowerShellで、Ubuntuではbashでコマンドが実行されます）。タスクが（シェルを起動せずに）プロセスを直接実行する必要がある場合は、vscode.ProcessExecutionを使用できます。ProcessExecutionには、拡張機能がプロセスに渡される引数を完全に制御できるという利点があります。ShellExecutionを使用すると、シェルコマンドの解釈（bashでのワイルドカード展開など）が利用されます。ShellExecutionが単一のコマンドラインで作成される場合、拡張機能はコマンド内の適切な引用符とエスケープ（たとえば、空白の処理）を確実に行う必要があります。

CustomExecution

一般的に、ShellExecutionまたはProcessExecutionはシンプルであるため、これらを使用するのが最善です。ただし、タスクが実行間で多くの保存された状態を必要とする場合、個別のスクリプトやプロセスとしてうまく機能しない場合、または出力の広範な処理が必要な場合は、CustomExecutionが適しているかもしれません。CustomExecutionの既存の用途は、通常、複雑なビルドシステム向けです。CustomExecutionには、タスクが実行されるときに実行されるコールバックしかありません。これにより、タスクができることの柔軟性が向上しますが、タスクプロバイダーがプロセス管理と出力解析を担当する必要があることも意味します。タスクプロバイダーは、Pseudoterminalを実装し、それをCustomExecutionコールバックから返す責任も負います。

return new vscode.Task(
  definition,
  vscode.TaskScope.Workspace,
  `${flavor} ${flags.join(' ')}`,
  CustomBuildTaskProvider.CustomBuildScriptType,
  new vscode.CustomExecution(
    async (): Promise<vscode.Pseudoterminal> => {
      // When the task is executed, this callback will run. Here, we setup for running the task.
      return new CustomBuildTaskTerminal(
        this.workspaceRoot,
        flavor,
        flags,
        () => this.sharedState,
        (state: string) => (this.sharedState = state)
      );
    }
  )
);

Pseudoterminalの実装を含む完全な例は、https://github.com/microsoft/vscode-extension-samples/tree/main/task-provider-sample/src/customTaskProvider.tsにあります。