Customize the Container Tools extension

The Container Tools extension includes several Visual Studio Code tasks to control the behavior of Docker build and run, and form the basis of container startup for debugging.

The tasks allow for a great deal of control and customization. The final configuration is a combination of general defaults, platform-specific defaults (such as Node.js, Python, or .NET), and user input. User input takes precedence when it conflicts with defaults.

All common features of Visual Studio Code tasks (for example, grouping tasks into compound tasks) are supported by Container Tools extension tasks. For more information on common task features and properties, see the Visual Studio Code custom task documentation.

Docker build task

The docker-build task builds images using the Docker command line (CLI). The task can be used by itself, or as part of a chain of tasks to run and/or debug an application within a container.

The most important configuration settings for the docker-build task are dockerBuild and platform:

The dockerBuild object specifies parameters for the Docker build command. Values specified by this object are applied directly to Docker build CLI invocation.
The platform property is a hint that changes how the docker-build task determines Docker build defaults.

See property reference for full list of all task properties.

Platform support

While the docker-build task in tasks.json can be used to build any image, the extension has explicit support (and simplified configuration) for Node.js, Python, and .NET Core.

Node.js (docker-build)

Minimal configuration using defaults

A Node.js-based image with no specific platform options can just set the platform property to node:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Node Image",
      "type": "docker-build",
      "platform": "node"
    }
  ]
}

Platform defaults

For Node.js-based images, the docker-build task infers the following options:

Property	Inferred Value
`dockerBuild.context`	The same directory in which the `package.json` resides.
`dockerBuild.dockerfile`	The file `Dockerfile` in the same directory as the `package.json` resides.
`dockerBuild.tag`	The application's `name` property in `package.json` (if defined), else the base name of the folder in which `package.json` resides.
`dockerBuild.pull`	Defaults to true in order to pull new base images before building.

Python (docker-build)

Minimal configuration using defaults

A Python-based image with no specific platform options can just set the platform property to python:

{
  "tasks": [
    {
      "type": "docker-build",
      "label": "docker-build",
      "platform": "python"
    }
  ]
}

Platform defaults

For Python-based images, the docker-build task infers the following options:

Property	Inferred Value
`dockerBuild.context`	The default context is the workspace folder.
`dockerBuild.dockerfile`	The default `Dockerfile` path will be in the root of the workspace folder.
`dockerBuild.tag`	The base name of the root workspace folder.
`dockerBuild.pull`	Defaults to true in order to pull new base images before building.

.NET (docker-build)

Minimal configuration using defaults

When you build a .NET-based image, you can omit the platform property and just set the netCore object (platform is implicitly set to netcore when netCore object is present). Note that appProject is a required property:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Build Node Image",
      "type": "docker-build",
      "netCore": {
        "appProject": "${workspaceFolder}/project.csproj"
      }
    }
  ]
}

Platform defaults

For .NET-based images, the docker-build task infers the following options:

Property	Inferred Value
`dockerBuild.context`	The root workspace folder.
`dockerBuild.dockerfile`	The file `Dockerfile` in the root workspace folder.
`dockerBuild.tag`	The base name of the root workspace folder.
`dockerBuild.pull`	Defaults to true in order to pull new base images before building.

Build task reference

Here are all properties available for configuring docker-build task. All properties are optional unless indicated otherwise.

Property	Description
`dockerBuild`	Options for controlling the `docker build` command executed (see below). Required unless `platform` is set.
`platform`	Determines the platform: .NET (`netcore`) or Node.js (`node`) and default settings for `docker build` command.
`node`	Determines options specific for Node.js projects (see below).
`python`	There are no object properties for Python in the `docker-build` task.
`netCore`	Determines options specific for .NET projects (see below).

dockerBuild object properties

Property	Description	`docker build` CLI Equivalent
`context`	The path to the build context. Required, unless inferred from the platform.	`PATH`
`dockerfile`	The path to the Dockerfile. Required, unless inferred from the platform.	`-f` or `--file`
`tag`	The tag applied to the image. Required, unless inferred from the platform.	`-t` or `--tag`
`buildArgs`	Build arguments applied to the command line. This is a list of key-value pairs.	`--build-arg`
`labels`	Labels added to the image. This is a list of key-value pairs (a JSON object). In addition to labels specified here, a label `com.microsoft.created-by`, set to `visual-studio-code` is added to the image. This behavior can be turned off by setting `includeDefaults` property of the `labels` object to false.	`--label`
`target`	The target in the Dockerfile to build to.	`--target`
`pull`	Whether or not to pull new base images before building.	`--pull`
`customOptions`	Any extra parameters to add before the context argument. No attempt is made to resolve conflicts with other options or validate this option.	(any)

node object properties (`docker-build` task)

Property	Description	Default
`package`	The path to the `package.json` file associated with the Dockerfile and `docker-build` task.	The file `package.json` in the root workspace folder.

netCore object properties (`docker-build` task)

Property	Description
`appProject`	The .NET project file (`.csproj`, `.fsproj`, etc.) associated with the Dockerfile and `docker-build` task. Required always.

Docker run task

The docker-run task in tasks.json creates and starts a container using the Docker command line (CLI). The task can be used by itself, or as part of a chain of tasks to debug an application within a container.

The most important configuration settings for the docker-run task are dockerRun and platform:

The dockerRun object specifies parameters for the Docker run command. Values specified by this object are applied directly to Docker run CLI invocation.
The platform property is a hint that changes how the docker-run task determines Docker run defaults.

See property reference for full list of all task properties.

Docker run platform support

While the docker-run task can be used to run any Docker image, the extension has explicit support (and simplified configuration) for Node.js, Python, and .NET.

Node.js (docker-run)

Minimal configuration using defaults

A Node.js-based image with no specific platform options can just set the platform property to node.

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run Node Image",
      "node": "docker-run",
      "platform": "node"
    }
  ]
}

Platform defaults

For Node.js-based images, the docker-run task infers the following options:

Property	Inferred Value
`dockerRun.command`	Generated from the npm `start` script in the `package.json` (if it exists), else generated from the `main` property in the `package.json`.
`dockerRun.containerName`	Derived from the application package name.
`dockerRun.image`	The tag from a dependent `docker-build` task (if one exists) or derived from the application package name, itself derived from the `name` property within `package.json` or the base name of the folder in which it resides.

Python (docker-run)

When building a Python-based image, you can omit the platform property and just set the python object (platform is implicitly set to python when python object is present)

Minimal configuration for Django Apps

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "python": {
    "args": ["runserver", "0.0.0.0:8000", "--nothreading", "--noreload"],
    "file": "path_to/manage.py"
  }
}

Minimal configuration for Flask Apps

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "dockerRun": {
    "env": {
      "FLASK_APP": "path_to/flask_entry_point.py"
    }
  },
  "python": {
    "args": ["run", "--no-debugger", "--no-reload", "--host", "0.0.0.0", "--port", "5000"],
    "module": "flask"
  }
}

Minimal configuration for General Apps

{
  "type": "docker-run",
  "label": "docker-run: debug",
  "dependsOn": ["docker-build"],
  "python": {
    "file": "path_to/app_entry_point.py"
  }
}

Platform defaults

For Python-based images, the docker-run task infers the following options:

Property	Inferred Value
`dockerRun.command`	Generated by the Python object and is called by the Python Debugger.
`dockerRun.containerName`	Derived from the base name of the root workspace folder.
`dockerRun.image`	The tag from a dependent docker-build task (if one exists) or derived from the base name of the root workspace folder.

.NET (docker-run)

Minimal configuration using defaults

When building a .NET-based image, you can omit the platform property and just set the netCore object (platform is implicitly set to netcore when netCore object is present). Note that appProject is a required property:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Run .NET Core Image",
      "type": "docker-run",
      "netCore": {
        "appProject": "${workspaceFolder}/project.csproj"
      }
    }
  ]
}

Platform defaults

For .NET-based images, the docker-run task infers the following options:

Property	Inferred Value
`dockerRun.containerName`	Derived from the base name of the root workspace folder.
`dockerRun.env`	Adds the following environment variables as required: `ASPNETCORE_ENVIRONMENT`, `ASPNETCORE_URLS`, and `DOTNET_USE_POLLING_FILE_WATCHER`.
`dockerRun.image`	The tag from a dependent `docker-build` task (if one exists) or derived from the base name of the root workspace folder.
`dockerRun.os`	`Linux`
`dockerRun.volumes`	Adds the following volumes as required: the local application folder, the source folder, the debugger folder, the NuGet package folder, and NuGet fallback folder.

Run task reference

Here are all properties available for configuring docker-run task. All properties are optional unless indicated otherwise.

Property	Description
`dockerRun`	Options for controlling the `docker run` command executed (see below). Required unless `platform` is set.
`platform`	Determines the platform: .NET (`netcore`) or Node.js (`node`) and default settings for `docker run` command.
`node`	For Node.js projects, this controls various options (see below).
`python`	For Python projects, this controls various options (see below).
`netCore`	For .NET projects, this controls various options (see below).

dockerRun object properties

Property	Description	CLI Equivalent
`image`	The name (tag) of the image to run. Required unless inferred from the platform.	`IMAGE`
`command`	The command to run upon starting the container. Required, unless inferred from the platform.	`COMMAND [ARG...]`
`containerName`	The name given to the started container. Required, unless inferred from the platform.	`--name`
`env`	Environment variables set in the container. This is a list of key-value pairs.	`-e` or `--env`
`envFiles`	This is a list of `.env` files.	`--env-file`

Customize the Container Tools extension

Docker build task

Platform support

Node.js (docker-build)

Python (docker-build)

.NET (docker-build)

Build task reference

dockerBuild object properties

node object properties (docker-build task)

netCore object properties (docker-build task)

Docker run task

Docker run platform support

Node.js (docker-run)

Python (docker-run)

.NET (docker-run)

Run task reference

dockerRun object properties

node object properties (`docker-build` task)

netCore object properties (`docker-build` task)