自定义 Docker 扩展
Docker 扩展包括几个 Visual Studio Code 任务,用于控制 Docker 构建和运行的行为,并构成调试容器启动的基础。
这些任务允许进行大量的控制和自定义。最终配置是通用默认值、平台特定默认值(例如 Node.js、Python 或 .NET)和用户输入的组合。当用户输入与默认值冲突时,用户输入优先。
Docker 扩展任务支持 Visual Studio Code 任务的所有常见功能(例如,将任务分组为复合任务)。有关常见任务功能和属性的更多信息,请参阅 Visual Studio Code 自定义任务文档。
Docker 构建任务
docker-build
任务使用 Docker 命令行 (CLI) 构建 Docker 镜像。该任务可以单独使用,也可以作为任务链的一部分,以便在 Docker 容器中运行和/或调试应用程序。
docker-build
任务最重要的配置设置是 dockerBuild
和 platform
dockerBuild
对象指定 Docker 构建命令的参数。此对象指定的值直接应用于 Docker build CLI 调用。platform
属性是一个提示,它会更改docker-build
任务确定 Docker 构建默认值的方式。
有关所有任务属性的完整列表,请参阅属性参考。
平台支持
虽然 tasks.json
中的 docker-build
任务可用于构建任何 Docker 镜像,但该扩展对 Node.js、Python 和 .NET Core 具有显式支持(和简化的配置)。
Node.js (docker-build)
使用默认值的最小配置
没有特定平台选项的基于 Node.js 的 Docker 镜像只需将 platform
属性设置为 node
{
"version": "2.0.0",
"tasks": [
{
"label": "Build Node Image",
"type": "docker-build",
"platform": "node"
}
]
}
平台默认值
对于 Node.js Docker 镜像,docker-build
任务会推断以下选项
属性 | 推断值 |
---|---|
dockerBuild.context |
package.json 所在的目录。 |
dockerBuild.dockerfile |
与 package.json 所在的目录相同的 Dockerfile 文件。 |
dockerBuild.tag |
应用程序在 package.json 中的 name 属性(如果已定义),否则为 package.json 所在文件夹的基本名称。 |
Python (docker-build)
使用默认值的最小配置
没有特定平台选项的基于 Python 的 Docker 镜像只需将 platform
属性设置为 python
{
"tasks": [
{
"type": "docker-build",
"label": "docker-build",
"platform": "python"
}
]
}
平台默认值
对于 Python Docker 镜像,docker-build
任务会推断以下选项
属性 | 推断值 |
---|---|
dockerBuild.context |
默认上下文是工作区文件夹。 |
dockerBuild.dockerfile |
默认 Dockerfile 路径将位于工作区文件夹的根目录中。 |
dockerBuild.tag |
根工作区文件夹的基本名称。 |
dockerBuild.pull |
默认为 true,以便在构建之前拉取新的基础镜像。 |
.NET (docker-build)
使用默认值的最小配置
构建基于 .NET 的 Docker 镜像时,可以省略 platform
属性,只需设置 netCore
对象(当存在 netCore
对象时,platform
隐式设置为 netcore
)。请注意,appProject
是必需的属性
{
"version": "2.0.0",
"tasks": [
{
"label": "Build Node Image",
"type": "docker-build",
"netCore": {
"appProject": "${workspaceFolder}/project.csproj"
}
}
]
}
平台默认值
对于基于 .NET 的镜像,docker-build
任务会推断以下选项
属性 | 推断值 |
---|---|
dockerBuild.context |
根工作区文件夹。 |
dockerBuild.dockerfile |
根工作区文件夹中的 Dockerfile 文件。 |
dockerBuild.tag |
根工作区文件夹的基本名称。 |
构建任务参考
以下是用于配置 docker-build
任务的所有可用属性。除非另有说明,否则所有属性均为可选。
属性 | 描述 |
---|---|
dockerBuild |
用于控制执行的 docker build 命令的选项(请参见下方)。除非设置了 platform ,否则为必需。 |
platform |
确定平台:.NET (netcore ) 或 Node.js (node ) 以及 docker build 命令的默认设置。 |
node |
确定 Node.js 项目的特定选项(请参见下方)。 |
python |
docker-build 任务中 Python 没有对象属性。 |
netCore |
确定 .NET 项目的特定选项(请参见下方)。 |
dockerBuild 对象属性
属性 | 描述 | docker build CLI 等效项 |
---|---|---|
context |
Docker 构建上下文的路径。 除非从平台推断,否则为必需。 |
PATH |
dockerfile |
Dockerfile 的路径。 除非从平台推断,否则为必需。 |
-f 或 --file |
tag |
应用于 Docker 镜像的标签。 除非从平台推断,否则为必需。 |
-t 或 --tag |
buildArgs |
应用于命令行的构建参数。这是一个键值对列表。 | --build-arg |
labels |
添加到 Docker 镜像的标签。这是一个键值对(JSON 对象)列表。 除了此处指定的标签外,还会将标签 com.microsoft.created-by 设置为 visual-studio-code 添加到镜像。可以通过将 labels 对象的 includeDefaults 属性设置为 false 来关闭此行为。 |
--label |
target |
要在 Dockerfile 中构建到的目标。 | --target |
pull |
是否在构建之前拉取新的基础镜像。 | --pull |
customOptions |
要在上下文参数之前添加的任何其他参数。不会尝试解决与其他选项的冲突或验证此选项。 | (任何) |
node 对象属性 (docker-build
任务)
属性 | 描述 | 默认值 |
---|---|---|
package |
与 Dockerfile 和 docker-build 任务关联的 package.json 文件的路径。 |
根工作区文件夹中的 package.json 文件。 |
netCore 对象属性 (docker-build
任务)
属性 | 描述 |
---|---|
appProject |
与 Dockerfile 和 docker-build 任务关联的 .NET 项目文件(.csproj 、.fsproj 等)。始终为必需项。 |
Docker 运行任务
tasks.json
中的 docker-run
任务使用 Docker 命令行 (CLI) 创建并启动 Docker 容器。该任务可以单独使用,也可以作为任务链的一部分,以在 Docker 容器中调试应用程序。
docker-run
任务最重要的配置设置是 dockerRun
和 platform
。
dockerRun
对象指定 Docker run 命令的参数。此对象指定的值将直接应用于 Docker run CLI 调用。platform
属性是一个提示,它会更改docker-run
任务确定 Docker run 默认值的方式。
有关所有任务属性的完整列表,请参阅属性参考。
Docker run 平台支持
尽管 docker-run
任务可用于运行任何 Docker 映像,但该扩展对 Node.js、Python 和 .NET 提供了显式支持(以及简化的配置)。
Node.js (docker-run)
使用默认值的最小配置
没有特定平台选项的基于 Node.js 的 Docker 映像只需将 platform
属性设置为 node
即可。
{
"version": "2.0.0",
"tasks": [
{
"label": "Run Node Image",
"node": "docker-run",
"platform": "node"
}
]
}
平台默认值
对于基于 Node.js 的 Docker 映像,docker-run
任务会推断以下选项:
属性 | 推断值 |
---|---|
dockerRun.command |
从 package.json 中的 npm start 脚本生成(如果存在),否则从 package.json 中的 main 属性生成。 |
dockerRun.containerName |
从应用程序包名称派生。 |
dockerRun.image |
来自依赖的 docker-build 任务(如果存在)的标签,或从应用程序包名称派生,应用程序包名称本身从 package.json 中的 name 属性或其所在的文件夹的基本名称派生。 |
Python (docker-run)
在构建基于 Python 的 Docker 映像时,可以省略 platform
属性,而只需设置 python
对象(当存在 python
对象时,platform
隐式设置为 python
)。
Django 应用程序的最小配置
{
"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"
}
}
Flask 应用程序的最小配置
{
"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"
}
}
通用应用程序的最小配置
{
"type": "docker-run",
"label": "docker-run: debug",
"dependsOn": ["docker-build"],
"python": {
"file": "path_to/app_entry_point.py"
}
}
平台默认值
对于基于 Python 的 Docker 映像,docker-run
任务会推断以下选项:
属性 | 推断值 |
---|---|
dockerRun.command |
由 Python 对象生成,并由 Python 调试器调用。 |
dockerRun.containerName |
从根工作区文件夹的基本名称派生。 |
dockerRun.image |
来自依赖的 docker-build 任务(如果存在)的标签,或从根工作区文件夹的基本名称派生。 |
.NET (docker-run)
使用默认值的最小配置
在构建基于 .NET 的 Docker 映像时,可以省略 platform
属性,而只需设置 netCore
对象(当存在 netCore
对象时,platform
隐式设置为 netcore
)。请注意,appProject
是必需属性。
{
"version": "2.0.0",
"tasks": [
{
"label": "Run .NET Core Image",
"type": "docker-run",
"netCore": {
"appProject": "${workspaceFolder}/project.csproj"
}
}
]
}
平台默认值
对于基于 .NET 的映像,docker-run
任务会推断以下选项:
属性 | 推断值 |
---|---|
dockerRun.containerName |
从根工作区文件夹的基本名称派生。 |
dockerRun.env |
根据需要添加以下环境变量:ASPNETCORE_ENVIRONMENT 、ASPNETCORE_URLS 和 DOTNET_USE_POLLING_FILE_WATCHER 。 |
dockerRun.image |
来自依赖的 docker-build 任务(如果存在)的标签,或从根工作区文件夹的基本名称派生。 |
dockerRun.os |
Linux |
dockerRun.volumes |
根据需要添加以下卷:本地应用程序文件夹、源文件夹、调试器文件夹、NuGet 包文件夹和 NuGet 回退文件夹。 |
运行任务参考
以下是可用于配置 docker-run
任务的所有属性。除非另有说明,否则所有属性都是可选的。
属性 | 描述 |
---|---|
dockerRun |
用于控制执行的 docker run 命令的选项(请参阅下文)。除非设置了 platform ,否则为必需。 |
platform |
确定平台:.NET (netcore ) 或 Node.js (node ) 以及 docker run 命令的默认设置。 |
node |
对于 Node.js 项目,这控制各种选项(请参阅下文)。 |
python |
对于 Python 项目,这控制各种选项(请参阅下文)。 |
netCore |
对于 .NET 项目,这控制各种选项(请参阅下文)。 |
dockerRun 对象属性
属性 | 描述 | CLI 等效项 |
---|---|---|
image |
要运行的映像的名称(标签)。 除非从平台推断得出,否则为必需项。 |
IMAGE |
command |
启动容器时要运行的命令。 除非从平台推断,否则为必需。 |
COMMAND [ARG...] |
containerName |
赋予已启动容器的名称。 除非从平台推断,否则为必需。 |
--name |
env |
在容器中设置的环境变量。这是一个键值对列表。 | -e 或 --env |
envFiles |
这是一个 .env 文件列表。 |
--env-file |
labels |
赋予已启动容器的标签。这是一个键值对列表。 | --label |
network |
容器将连接到的网络的名称。 | --network |
networkAlias |
已启动容器的网络范围别名。 | --network-alias |
os |
默认值为 Linux ,另一个选项是 Windows 。使用的容器操作系统。 |
不适用 |
ports |
要从容器发布(映射)到主机的端口。这是一个对象列表(请参阅下文)。 | -p 或 --publish |
portsPublishAll |
是否发布 Docker 映像公开的所有端口。如果未显式发布端口,则默认为 true 。 |
-P |
extraHosts |
要添加到容器以进行 DNS 解析的主机。这是一个对象列表(请参阅下文)。 | --add-host |
volumes |
要映射到已启动容器中的卷。这是一个对象列表(请参阅下文)。 | -v 或 --volume |
remove |
是否在容器停止后删除它。 | --rm |
customOptions |
要在映像参数之前添加的任何额外参数。不会尝试解决与其他选项的冲突或验证此选项。 | (任何) |
ports 对象属性
属性 | 描述 | 默认值 |
---|---|---|
containerPort |
绑定到容器的端口号。 必需。 |
|
hostPort |
绑定到主机的端口号。 | (由 Docker 随机选择) |
protocol |
绑定的协议(tcp 或 udp )。 |
tcp |
extraHosts 对象属性
属性 | 描述 |
---|---|
hostname |
用于 DNS 解析的主机名。 必需。 |
ip |
与上述主机名关联的 IP 地址。 必需。 |
volumes 对象属性
属性 | 描述 | 默认值 |
---|---|---|
localPath |
要映射的本地计算机上的路径。 必需。 |
|
containerPath |
容器中将映射本地路径的路径。 必需。 |
|
permissions |
容器在映射路径上具有的权限。可以是 ro (只读)或 rw (读写)。 |
取决于容器。 |
node 对象属性 (docker-run
任务)
属性 | 描述 | 默认值 |
---|---|---|
package |
与 docker-run 任务关联的 package.json 文件的路径。 |
根工作区文件夹中的 package.json 文件。 |
enableDebugging |
是否在容器内启用调试。 | false |
inspectMode |
定义应用程序和调试器之间的初始交互(default 或 break )。值 default 允许应用程序运行,直到调试器附加。值 break 防止应用程序运行,直到调试器附加。 |
default |
inspectPort |
应在其上进行调试的端口。 | 9229 |
python 对象属性 (docker-run
任务)
属性 | 描述 | 默认值 |
---|---|---|
args |
传递给 Python 应用程序的参数。 | 取决于平台。上面显示了脚手架的默认值 |
debugPort |
调试器将侦听的端口。 | 5678 |
wait |
是否等待调试器附加。 | true |
module |
要运行的 Python 模块(应仅选择模块或文件)。 | |
file |
要运行的 Python 文件(应仅选择模块或文件)。 |
netCore 对象属性 (docker-run
任务)
属性 | 描述 |
---|---|
appProject |
与 docker-run 任务关联的 .NET 项目文件(.csproj 、.fsproj 等)。必需。 |
configureSsl |
是否配置 ASP.NET Core SSL 证书和其他设置以在容器中的服务上启用 SSL。 |
enableDebugging |
是否启用已启动容器以进行调试。这将推断调试所需的其他卷映射和其他选项。 |
Docker Compose 任务
tasks.json
中的 docker-compose
任务使用 Docker Compose 命令行 (CLI) 创建并启动 Docker 容器。该任务可以单独使用,也可以作为任务链的一部分,以在 Docker 容器中调试应用程序。
docker-compose
任务最重要的配置设置是 dockerCompose
。
dockerCompose
对象指定 Docker Compose 命令的参数。此对象指定的值将直接应用于 Docker Compose CLI 调用。
有关所有任务属性的完整列表,请参阅属性参考。
配置示例
{
"version": "2.0.0",
"tasks": [
{
"label": "Run docker-compose up",
"type": "docker-compose",
"dockerCompose": {
"up": {
"detached": true,
"build": true,
"services": ["myservice"]
},
"files": [
"${workspaceFolder}/docker-compose.yml",
"${workspaceFolder}/docker-compose.debug.yml"
]
}
}
]
}
Compose 任务参考
以下是可用于配置 docker-compose
任务的所有属性。除非另有说明,否则所有属性都是可选的。
属性 | 描述 |
---|---|
dockerCompose |
用于控制执行的 docker-compose 命令的选项(请参阅下文)。必需。 |
dockerCompose 对象属性
属性 | 描述 | CLI 等效项 |
---|---|---|
up |
运行 docker-compose up 命令。必须指定此项或 down ,但不能同时指定两者。 |
docker-compose up |
down |
运行 docker-compose down 命令。必须指定此项或 up ,但不能同时指定两者。 |
docker-compose down |
files |
要在 docker-compose 命令中使用的 Docker Compose YAML 文件列表。如果未指定,则 Docker Compose CLI 会查找 docker-compose.yml 和 docker-compose.override.yml 。 |
-f <file> |
envFile |
读取并应用于容器的环境变量文件。 | --env-file <file> |
projectName |
在命名和标记 Docker 对象时要使用的备用项目名称。如果在组合启动时使用备用项目名称,则在组合关闭时必须指定相同的项目名称。 | --project-name <name> |
up 对象属性
属性 | 描述 | CLI 等效项 | 默认值 |
---|---|---|---|
detached |
是否以分离模式运行。 | -d |
true |
build |
是否在运行之前生成。 | --build |
true |
scale |
要运行的每个服务的实例数。这是一个键值对列表。 | --scale SERVICE=NUM |
|
services |
要启动的服务子集。不能与 profiles 组合使用。 |
[SERVICE...] |
(全部) |
profiles |
要启动的配置文件子集。不能与 services 结合使用。 |
--profile <profile> |
(全部) |
customOptions |
在 up 参数之后添加的任何额外参数。 不会尝试解决与其他选项的冲突或验证此选项。 |
(任何) |
down 对象属性
属性 | 描述 | CLI 等效项 | 默认值 |
---|---|---|---|
removeImages |
是否删除镜像,以及删除哪些镜像。 all 将删除任何服务使用的所有镜像,local 将仅删除没有自定义标签的镜像。 如果不设置此项,则不会删除任何镜像。 |
--rmi |
|
removeVolumes |
是否删除命名的卷。 | -v |
false |
customOptions |
在 down 参数之后添加的任何额外参数。 不会尝试解决与其他选项的冲突或验证此选项。 |
(任何) |
命令自定义
当您执行各种操作时,例如构建镜像、运行容器、连接到容器以及查看容器日志,Docker 扩展会执行许多 Docker CLI 命令。 其中一些命令有大量可选参数,通常在非常特定的场景中使用。 作为上述 Visual Studio Code 任务的替代方案,当任务未使用时,可以自定义多个命令。
例如, Compose Up 命令中的令牌 ${serviceList}
和 ${profileList}
允许轻松启动 Docker Compose YAML 文件中的服务子集。
对于每个可自定义的 Docker 命令,都有一个配置设置可用于设置要执行的模板。 或者,您可以定义多个模板,可以选择使用正则表达式,当匹配时,提示应该使用哪个模板的上下文。 这些模板支持一些类似于 launch.json
和 tasks.json
的令牌,例如 ${workspaceFolder}
。
设置 JSON 架构
您有两个选项来配置每个模板(如下所列)。 第一个选项是覆盖默认行为的单个模板。
{
"docker.commands.build": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
}
第二个选项是多个模板,将根据 match
正则表达式以及用户输入进行选择。
例如,以下示例中显示了三个模板
{
"docker.commands.build": [
{
"label": "Default build command",
"template": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
},
{
"label": "Alpine-specific build command",
"template": "docker build -p 1234:1234 -f \"${dockerfile}\" -t ${tag} \"${context}\"",
"match": "alpine"
}
]
}
选择行为
选择要执行的命令模板基于以下规则
- 如果未配置任何设置,则选择默认命令模板。
- 如果仅配置了单个模板(如上面的第一个示例),则选择该模板。
- 如果配置了多个模板
- 将检查受约束的模板。受约束的模板具有
match
。match
正则表达式将与上下文提示进行比较--例如,镜像名称、容器名称等。 - 如果应用了多个受约束的模板,将提示用户选择。如果仅应用一个,则不会提示用户。
- 如果没有适用的受约束的模板,则会检查不受约束的模板。不受约束的模板没有
match
,因此始终适用。 - 如果应用了多个不受约束的模板,将提示用户选择。如果仅应用一个,则不会提示用户。
- 将检查受约束的模板。受约束的模板具有
Docker 构建
配置设置 | 默认值 |
---|---|
docker.commands.build |
${containerCommand} build --rm -f "${dockerfile}" -t ${tag} "${context}" |
支持的令牌
令牌 | 描述 |
---|---|
${containerCommand} |
用于执行容器命令的 CLI 命令/可执行文件。 |
${dockerfile} |
所选 Dockerfile 的工作区相对路径。 |
${tag} |
用户在调用构建命令时输入/确认的值。 如果之前已构建,则默认为该 Dockerfile 之前输入的值。 |
${context} |
如果设置,则为 docker.imageBuildContextPath 配置设置的值。 否则,为 Dockerfile 所在的相对于工作区的文件夹。 |
注意: 如果
docker.commands.build
设置不包含${tag}
令牌,则不会提示用户输入/确认标签。
注意:
match
正则表达式将与所选 Dockerfile 名称和工作区文件夹名称进行比较。
Docker 运行
配置设置 | 默认值 |
---|---|
docker.commands.run |
${containerCommand} run --rm -d ${exposedPorts} ${tag} |
docker.commands.runInteractive |
${containerCommand} run --rm -it ${exposedPorts} ${tag} |
支持的令牌
令牌 | 描述 |
---|---|
${containerCommand} |
用于执行容器命令的 CLI 命令/可执行文件。 |
${exposedPorts} |
从镜像中公开的端口列表(最终来自 Dockerfile )生成,其中每个公开的端口都映射到本地计算机上的相同端口。 例如,"EXPOSE 5000 5001" 将生成 "-p 5000:5000 -p 5001:5001" 。 |
${tag} |
所选镜像的完整标签。 |
注意:
match
正则表达式将与所选镜像的完整标签进行比较。
Docker 连接
配置设置 | 默认值 |
---|---|
docker.commands.attach |
${containerCommand} exec -it ${containerId} ${shellCommand} |
支持的令牌
令牌 | 描述 |
---|---|
${containerCommand} |
用于执行容器命令的 CLI 命令/可执行文件。 |
${containerId} |
要连接到的容器的 ID。 |
${shellCommand} |
如果容器中存在 bash ,则在此处替换,否则为 sh 。 在 Windows 容器中,始终使用 cmd 。 |
注意:
match
正则表达式将与容器名称和容器镜像的完整标签进行比较。
Docker 日志
配置设置 | 默认值 |
---|---|
docker.commands.logs |
${containerCommand} logs -f ${containerId} |
支持的令牌
令牌 | 描述 |
---|---|
${containerCommand} |
用于执行容器命令的 CLI 命令/可执行文件。 |
${containerId} |
要查看日志的容器的 ID。 |
注意:
match
正则表达式将与容器名称和容器镜像的完整标签进行比较。
Docker Compose Up
配置设置 | 默认值 |
---|---|
docker.commands.composeUp |
${composeCommand} ${configurationFile} up ${detached} ${build} |
支持的令牌
令牌 | 描述 |
---|---|
${configurationFile} |
设置为 -f 加上所选 Docker Compose YAML 文件的相对于工作区的路径。 |
${detached} |
如果配置设置 docker.dockerComposeDetached 设置为 true ,则设置为 -d 。 否则,设置为 "" 。 |
${build} |
如果配置设置 docker.dockerComposeBuild 设置为 true ,则设置为 --build 。 否则,设置为 "" 。 |
${serviceList} |
如果指定,则在运行命令时提示启动服务的子集。 |
${profileList} |
如果指定,并且 Docker Compose YAML 文件包含配置文件,则在运行命令时提示启动配置文件的子集。 |
${composeCommand} |
如果设置了 docker.composeCommand 设置的值,则设置为该值,否则扩展将尝试自动确定要使用的命令(docker compose 或 docker-compose )。 |
Docker Compose Down
配置设置 | 默认值 |
---|---|
docker.commands.composeDown |
${composeCommand} ${configurationFile} down |
支持的令牌
令牌 | 描述 |
---|---|
${configurationFile} |
设置为 -f 加上所选 Docker Compose YAML 文件的相对于工作区的路径。 |
${composeCommand} |
如果设置了 docker.composeCommand 设置的值,则设置为该值,否则扩展将尝试自动确定要使用的命令(docker compose 或 docker-compose )。 |
其他支持的令牌
除了特定于命令的支持令牌外,以下令牌在所有命令模板中均受支持
令牌 | 描述 |
---|---|
${workspaceFolder} |
所选工作区文件夹路径。 |
${config:some.setting.identifier} |
任何配置设置的值,只要它是字符串、数字或布尔值。 这些设置标识符可以任意定义,不需要属于 Visual Studio Code 或任何扩展。 |
${env:Name} |
环境变量的值。 |
${command:commandID} |
命令的字符串返回值。 |