Task Provider

Users normally define tasks in Visual Studio Code in a tasks.json file. However, there are some tasks during software development that can be automatically detected by a VS Code extension with a Task Provider. When the Tasks: Run Task command is run from VS Code, all active Task Providers contribute tasks that the user can run. While the tasks.json file lets the user manually define a task for a specific folder or workspace, a Task Provider can detect details about a workspace and then automatically create a corresponding VS Code Task. For example, a Task Provider could check if there is a make file and create a build task. This topic describes how extensions can auto-detect and provide tasks to end-users.

This guide teaches you how to build a Task Provider that auto-detects tasks defined in Rakefiles. The complete source code is at: https://github.com/Microsoft/vscode-extension-samples/tree/master/task-provider-sample.

Task Definition

To uniquely identify a task in the system, an extension contributing a task needs to define the properties that identify a task. In the Rake example, the task definition looks like this:

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

This contributes a task definition for rake tasks. The task definition has two attributes task and file. task is the name of the Rake task and file points to the Rakefile that contains the task. The task property is required, the file property is optional. If the file attribute is omitted, the Rakefile in the root of the workspace folder is used.

Task provider

Analogous to language providers that let extensions support code completion, an extension can register a task provider to compute all available tasks. This is done using the vscode.tasks namespace as shown in the following code snippet:

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,
        definition.task,
        'rake',
        new vscode.ShellExecution(`rake ${definition.task}`)
      );
    }
    return undefined;
  }
});

Like provideTasks, the resolveTask method is called by VS Code to get tasks from the extension. resolveTask is called after provideTasks, and is intended to provide an optional performance increase for providers that implement it but don't provide tasks from provideTasks. It is good practice to have a setting that allows users to turn off individual task providers, so this is common. A user might notice that tasks from a specific provider are slower to get and turn off the provider. In this case, the user might still reference some of the tasks from this provider in their tasks.json. If resolveTask is not implemented, then there will be a warning that the task in their tasks.json was not created. With resolveTask an extension can still provide a task for the task defined in tasks.json.

The getRakeTasks implementation does the following:

  • Lists all rake tasks defined in a Rakefile using the rake -AT -f Rakefile command.
  • Parses the stdio output.
  • For every listed task, creates a vscode.Task implementation.

Since a Rake task instantiation needs a task definition as defined in the package.json file, VS Code also defines the structure using a TypeScript interface like this:

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

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

Assuming that the output comes from a task called compile, the corresponding task creation then looks like this:

let task = new vscode.Task(
  { type: 'rake', task: 'compile' },
  'compile',
  'rake',
  new vscode.ShellExecution('rake compile')
);

For every task listed in the output, a corresponding VS Code task is created using the above pattern and then returns the array of all tasks from the getRakeTasks call.

The ShellExecution executes the rake compile command in the shell that is specific for the OS (for example under Windows the command would be executed in PowerShell, under Ubuntu it'd be executed in bash). If the task should directly execute a process (without spawning a shell), vscode.ProcessExecution can be used. ProcessExecution has the advantage that the extension has full control over the arguments passed to the process. Using ShellExecution makes use of the shell command interpretation (like wildcard expansion under bash). If the ShellExecution is created with a single command line, then the extension needs to ensure proper quoting and escaping (for example to handle whitespace) inside the command.