任务提供者

用户通常在文件中定义Visual Studio Code 中的任务tasks.json。但是，软件开发过程中的一些任务可以通过带有任务提供程序的 VS Code 扩展自动检测到。当从 VS Code 运行“任务：运行任务”命令时，所有活动任务提供程序都会提供用户可以运行的任务。虽然该tasks.json文件允许用户手动为特定文件夹或工作区定义任务，但任务提供程序可以检测有关工作区的详细信息，然后自动创建相应的 VS Code 任务。例如，任务提供者可以检查是否存在特定的构建文件（例如make或Rakefile），并创建构建任务。本主题描述扩展如何自动检测并向最终用户提供任务。

本指南教您如何构建一个自动检测Rakefiles中定义的任务的任务提供程序。完整的源代码位于：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。task是 Rake 任务的名称，并file指向Rakefile包含该任务的 。该task属性是必需的，该file属性是可选的。如果file省略该属性，Rakefile则使用工作区文件夹根目录中的 。

When 子句

任务定义可以可选地具有when属性。该when属性指定该类型任务可用的条件。该属性的功能与 VS Code 中其他有属性的地方when相同。创建任务定义时应始终考虑以下上下文：when

  • shellExecutionSupported：当 VS Code 可以运行ShellExecution任务时为 true，例如 VS Code 作为桌面应用程序运行或使用远程扩展之一（例如 Dev 容器）时。
  • processExecutionSupported：当 VS Code 可以运行ProcessExecution任务时为 true，例如 VS Code 作为桌面应用程序运行或使用远程扩展之一（例如 Dev 容器）时。目前，它始终具有与 相同的值shellExecutionSupported。
  • customExecutionSupported：当 VS Code 可以运行时为 true CustomExecution。这始终是正确的。

任务提供者

类似于让扩展支持代码完成的语言提供程序，扩展可以注册任务提供程序来计算所有可用任务。这是使用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实现执行以下操作：

  • 列出Rakefile使用rake -AT -f 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。

在特定于操作系统的 shell 中执行命令（例如，在 Windows 下，该命令将在 PowerShell 中执行，在 Ubuntu 下，它将在 bash 中执行）ShellExecution。rake compile如果任务应该直接执行一个进程（不生成 shell），则vscode.ProcessExecution可以使用。ProcessExecution优点是扩展可以完全控制传递给进程的参数。usingShellExecution利用 shell 命令解释（如 bash 下的通配符扩展）。如果ShellExecution使用单个命令行创建，则扩展需要确保命令内正确的引用和转义（例如处理空格）。

定制执行

一般来说，最好使用ShellExecution或，ProcessExecution因为它们很简单。但是，如果您的任务需要在运行之间保存大量状态，作为单独的脚本或进程不能很好地工作，或者需要对输出进行大量处理，那么 a 可能是CustomExecution一个不错的选择。现有用途CustomExecution通常用于复杂的构建系统。ACustomExecution只有一个在任务运行时执行的回调。这使得任务可以执行的操作具有更大的灵活性，但这也意味着任务提供者负责需要发生的任何流程管理和输出解析。任务提供者还负责实现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。

11/1/2023