Task Templates

Task configurations offer users a freeform, highly-configurable way of running external operations from within the IDE.

The simplest way of using them is by adding a basic “Run Script” configuration that is always available from a user’s project settings. This allows the user to define a script that will execute either on the local machine or a remote server when the configuration is run, forwarding its output to an IDE output report.

Extensions can extend this idea further by offering Task Templates.

Defining a template in your extension adds a new item to the “Add Task” interface of a user’s Project Settings. This allows a user to instantiate your template as one or more new configurations within their project. Each configuration added references the template in your extension for configuration options, allowing the extension to evolve without the need to recreate configurations.

A template defines what command is executed when the user runs a configuration created from it, along with the arguments it is passed. Arguments are defined a way that allows them to be edited by a user in the configuration editor, much like an extension’s preferences.

Defining a Template

The extension’s extension.json can include a taskTemplates object defining the templates that are exposed by the extension.

Each item in the object is keyed by the template’s identifier, which should not change once an extension is released: Configurations created from it reference this identifier to determine how the configuration is executed.

The value of each item is an object defining how the template behaves.

Here is an example of a configuration which executes a local PHP development web server:

"taskTemplates": {
    "webserver": {
        "name": "PHP Webserver",
        "description": "Runs the PHP development server.",
        "persistent": true,
        "task": {
            "shell": true,
            "command": "php",
            "args": [
                "-S", "$(Config:php.host):$(Config:php.port)",
                "-t", "$(Config:php.document-root)",
                "$(Config:php.custom-args)"
            ],
            "env": {
            }
        },
        "config": [
            {
                "key": "php.host",
                "title": "Host",
                "type": "string",
                "placeholder": "localhost",
                "default": "localhost"
            },
            {
                "key": "php.port",
                "title": "Port",
                "type": "number",
                "placeholder": "8000",
                "default": 8000,
                "min": 1,
                "max": 65535
            },
            {
                "key": "php.document-root",
                "title": "Document Root",
                "type": "path",
                "default": "."
            },
            {
                "key": "php.custom-args",
                "title": "Additional Arguments",
                "description": "Custom arguments to pass to the PHP webserver command.",
                "type": "string"
            }
        ]
    }
}

Task

The most important details of a template are defined in its task section. These options define how the resulting configuration is executed.

Value Description
command The executable command to invoke
shell If true, the command will be executed within a shell
args An array of interpolated strings passed to the command
env Interpolated environment variables set for the command

The command value is the executable name that will be invoked by the IDE. This may be a path to a script, relative to the extension root (such as Scripts/run.sh), or a command available on the user’s PATH.

For most cases, be careful when specifying paths for the command. If the path is not valid on all user’s computers it can cause the run to fail. Use absolute paths when the expectation is that the tool being invoked is required to be at this location. Otherwise, use a singular command name that will be interpreted against the user’s PATH, or against the extension’s container. Alternatively, the command value may contain string substitutions (see Arguments, below) that allow the configuration itself to build the path that is referenced at runtime.

Arguments

The args and env values can be interpolated, meaning the values may contain special string substitutions that are resolved at runtime. These substitutions follow a similar format to shell substitutions: $VariableName for singular variables, and $(Expression) for more complex expressions. The former is simply a shorthand subset of the latter which can only contain alphanumeric characters and the underscore. The variables and expressions available include those listed in [Variables & Expressions][variables], as well as configuration items defined by the template itself (see “Configuration” below).

Configuration

Each template may define a config section, which uses the same format as Preferences items. These configuration items may be referenced in the string substitution of arguments and environment passed to the template’s executable using the format $(Config:my.config-key). The value will be checked against those set for the configuration, as well as the user’s project and global preferences.