參加你附近的 ,瞭解 VS Code 中的 AI 輔助開發。

自定義容器工具擴充套件

容器工具擴充套件包含幾個 Visual Studio Code 任務,用於控制 Docker 構建執行的行為,並構成除錯容器啟動的基礎。

這些任務允許進行大量的控制和自定義。最終配置是通用預設值、平臺特定預設值(例如 Node.js、Python 或 .NET)和使用者輸入的組合。當用戶輸入與預設值衝突時,使用者輸入優先。

容器工具擴充套件任務支援 Visual Studio Code 任務的所有常見功能(例如,將任務分組為複合任務)。有關常見任務功能和屬性的更多資訊,請參閱 Visual Studio Code 自定義任務文件。

Docker 構建任務

docker-build 任務使用 Docker 命令列 (CLI) 構建映象。該任務可以單獨使用,也可以作為任務鏈的一部分,用於在容器內執行和/或除錯應用程式。

docker-build 任務最重要的配置設定是 dockerBuildplatform

  • dockerBuild 物件指定 Docker 構建命令的引數。此物件指定的值直接應用於 Docker 構建 CLI 呼叫。
  • platform 屬性是一個提示,它改變了 docker-build 任務確定 Docker 構建預設值的方式。

有關所有任務屬性的完整列表,請參閱屬性參考

平臺支援

雖然 tasks.json 中的 docker-build 任務可以用於構建任何映象,但該擴充套件明確支援(並簡化了配置)Node.js、Python 和 .NET Core。

Node.js (docker-build)

使用預設值的最小配置

沒有特定平臺選項的 Node.js 映象只需將 platform 屬性設定為 node

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

平臺預設值

對於基於 Node.js 的映象,docker-build 任務推斷以下選項

屬性 推斷值
dockerBuild.context package.json 所在的同一目錄。
dockerBuild.dockerfile package.json 位於同一目錄中的 Dockerfile 檔案。
dockerBuild.tag package.json 中應用程式的 name 屬性(如果已定義),否則為 package.json 所在資料夾的基本名稱。
dockerBuild.pull 預設為 true,以便在構建之前拉取新的基礎映象。

Python (docker-build)

使用預設值的最小配置

沒有特定平臺選項的基於 Python 的映象只需將 platform 屬性設定為 python

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

平臺預設值

對於基於 Python 的映象,docker-build 任務推斷以下選項

屬性 推斷值
dockerBuild.context 預設上下文是工作區資料夾。
dockerBuild.dockerfile 預設的 Dockerfile 路徑將在工作區資料夾的根目錄。
dockerBuild.tag 根工作區資料夾的基本名稱。
dockerBuild.pull 預設為 true,以便在構建之前拉取新的基礎映象。

.NET (docker-build)

使用預設值的最小配置

當您構建基於 .NET 的映象時,可以省略 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 根工作區資料夾的基本名稱。
dockerBuild.pull 預設為 true,以便在構建之前拉取新的基礎映象。

構建任務參考

以下是配置 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 構建上下文的路徑。
必需,除非從平臺推斷。
PATH
dockerfile Dockerfile 的路徑。
必需,除非從平臺推斷。
-f--file
tag 應用於映象的標籤。
必需,除非從平臺推斷。
-t--tag
buildArgs 應用於命令列的構建引數。這是一個鍵值對列表。 --build-arg
labels 新增到映象的標籤。這是一個鍵值對列表(一個 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-run 任務最重要的配置設定是 dockerRunplatform

  • dockerRun 物件指定 Docker 執行命令的引數。此物件指定的值直接應用於 Docker 執行 CLI 呼叫。
  • platform 屬性是一個提示,它改變了 docker-run 任務確定 Docker 執行預設值的方式。

有關所有任務屬性的完整列表,請參閱屬性參考

Docker 執行平臺支援

雖然 docker-run 任務可以用於執行任何 Docker 映象,但該擴充套件明確支援(並簡化了配置)Node.js、Python 和 .NET。

Node.js (docker-run)

使用預設值的最小配置

沒有特定平臺選項的 Node.js 映象只需將 platform 屬性設定為 node

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

平臺預設值

對於基於 Node.js 的映象,docker-run 任務推斷以下選項

屬性 推斷值
dockerRun.command package.json 中的 npm start 指令碼生成(如果存在),否則從 package.json 中的 main 屬性生成。
dockerRun.containerName 從應用程式包名稱派生。
dockerRun.image 來自依賴的 docker-build 任務的標籤(如果存在),或從應用程式包名稱派生,該名稱本身從 package.json 中的 name 屬性或其所在資料夾的基本名稱派生。

Python (docker-run)

當構建基於 Python 的映象時,可以省略 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-run 任務推斷以下選項

屬性 推斷值
dockerRun.command 由 Python 物件生成,並由 Python 偵錯程式呼叫。
dockerRun.containerName 從根工作區資料夾的基本名稱派生。
dockerRun.image 來自依賴的 docker-build 任務的標籤(如果存在),或從根工作區資料夾的基本名稱派生。

.NET (docker-run)

使用預設值的最小配置

當構建基於 .NET 的映象時,可以省略 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_ENVIRONMENTASPNETCORE_URLSDOTNET_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 繫結的協議(tcpudp)。 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 定義應用程式和偵錯程式之間的初始互動(defaultbreak)。
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-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.ymldocker-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 CLI 命令。其中一些命令具有大量可選引數,通常用於非常特定的場景。作為上述 Visual Studio Code 任務的替代方案,在不使用任務時可以自定義幾個命令。

例如,Compose Up 命令中的令牌 ${serviceList}${profileList} 允許輕鬆啟動 Docker Compose YAML 檔案中的服務子集。

對於每個可自定義的 Docker 命令,都有一個配置設定可用於設定要執行的模板。或者,您可以定義多個模板,可選地帶有正則表示式,當匹配時,它會提示應使用模板的上下文。這些模板支援一些類似於 launch.jsontasks.json 的令牌,例如 ${workspaceFolder}

設定 JSON 模式

您有兩種配置每個模板的選項(如下所列)。第一個選項是覆蓋預設行為的單個模板。

{
  "containers.commands.build": "docker build --rm -f \"${dockerfile}\" -t ${tag} \"${context}\""
}

第二個選項是多個模板,將根據 match 正則表示式和使用者輸入進行選擇。

例如,以下示例中顯示了三個模板

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

選擇行為

選擇要執行的命令模板基於以下規則

  1. 如果未配置任何設定,則選擇預設命令模板。
  2. 如果只配置了一個模板(上面的第一個示例),則選擇該模板。
  3. 如果配置了多個模板
    1. 檢查受限模板。受限模板具有 matchmatch 正則表示式將與上下文提示進行比較——例如,映象名稱、容器名稱等。
    2. 如果多個受限模板適用,將提示使用者選擇。如果只有一個適用,則不會提示使用者。
    3. 如果沒有適用的受限模板,則檢查非受限模板。非受限模板沒有 match,因此始終適用。
    4. 如果多個非受限模板適用,將提示使用者選擇。如果只有一個適用,則不會提示使用者。

Docker 構建

配置設定 預設值
docker.commands.build ${containerCommand} build --rm -f "${dockerfile}" -t ${tag} "${context}"

支援的令牌

標記 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔案。
${dockerfile} 所選 Dockerfile 的工作區相對路徑。
${tag} 使用者在呼叫構建命令時輸入/確認的值。如果之前已構建,則預設為該 Dockerfile 之前輸入的值。
${context} 如果設定,則為 containers.imageBuildContextPath 配置設定的值。否則,為 Dockerfile 所在的工作區相對資料夾。

注意:如果 containers.commands.build 設定不包含 ${tag} 令牌,使用者將不會被提示輸入/確認標籤。

注意match 正則表示式將與所選 Dockerfile 名稱和工作區資料夾名稱進行比較。

Docker 執行

配置設定 預設值
containers.commands.run ${containerCommand} run --rm -d ${exposedPorts} ${tag}
containers.commands.runInteractive ${containerCommand} run --rm -it ${exposedPorts} ${tag}

支援的令牌

標記 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔案。
${exposedPorts} 根據映象中公開埠列表(最終來自 Dockerfile)生成,其中每個公開埠都對映到本地機器上的相同埠。例如,"EXPOSE 5000 5001" 將生成 "-p 5000:5000 -p 5001:5001"
${tag} 所選映象的完整標籤。

注意match 正則表示式將與所選映象的完整標籤進行比較。

容器附加

配置設定 預設值
containers.commands.attach ${containerCommand} exec -it ${containerId} ${shellCommand}

支援的令牌

標記 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔案。
${containerId} 要附加到的容器的 ID。
${shellCommand} 如果容器中存在 bash,則在此處替換,否則為 sh。在 Windows 容器中,始終使用 cmd

注意match 正則表示式將與容器名稱和容器映象的完整標籤進行比較。

容器日誌

配置設定 預設值
containers.commands.logs ${containerCommand} logs -f ${containerId}

支援的令牌

標記 描述
${containerCommand} 用於執行容器命令的 CLI 命令/可執行檔案。
${containerId} 要檢視日誌的容器的 ID。

注意match 正則表示式將與容器名稱和容器映象的完整標籤進行比較。

Docker Compose Up

配置設定 預設值
containers.commands.composeUp ${composeCommand} ${configurationFile} up ${detached} ${build}

支援的令牌

標記 描述
${configurationFile} 設定為 -f 加上所選 Docker Compose YAML 檔案的相對於工作區的路徑。
${detached} 如果配置設定 containers.composeDetached 設定為 true,則設定為 -d。否則,設定為 ""
${build} 如果配置設定 containers.composeBuild 設定為 true,則設定為 --build。否則,設定為 ""
${serviceList} 如果指定,則在執行命令時提示選擇要啟動的服務子集。
${profileList} 如果指定且 Docker Compose YAML 檔案包含配置檔案,則在執行命令時提示選擇要啟動的配置檔案子集。
${composeCommand} 如果設定了 containers.composeCommand 設定的值,則設定為該值,否則擴充套件將嘗試自動確定要使用的命令(docker composedocker-compose)。

Docker Compose Down

配置設定 預設值
containers.commands.composeDown ${composeCommand} ${configurationFile} down

支援的令牌

標記 描述
${configurationFile} 設定為 -f 加上所選 Docker Compose YAML 檔案的相對於工作區的路徑。
${composeCommand} 如果設定了 containers.composeCommand 設定的值,則設定為該值,否則擴充套件將嘗試自動確定要使用的命令(docker composedocker-compose)。

其他支援的令牌

除了命令特定的支援令牌外,所有命令模板都支援以下令牌

標記 描述
${workspaceFolder} 所選工作區資料夾路徑。
${config:some.setting.identifier} 任何配置設定的值,只要它是字串、數字或布林值。這些設定識別符號可以任意定義,不需要屬於 Visual Studio Code 或任何擴充套件。
${env:Name} 環境變數的值。
${command:commandID} 命令的字串返回值。