自訂 Container Tools 擴充功能

Container Tools 擴充功能包含數個 Visual Studio Code 工作,用以控制 Docker 建置 (build)執行 (run) 的行為,並構成除錯時容器啟動的基礎。

這些工作提供了極大的控制權與自訂空間。最終配置是通用預設值、平台特定預設值(如 Node.js、Python 或 .NET)以及使用者輸入的結合。當使用者輸入與預設值衝突時,以使用者輸入為優先。

Visual Studio Code 工作的所有常見功能(例如將工作分組為複合工作)皆受 Container Tools 擴充功能工作支援。如需關於常見工作功能與屬性的詳細資訊,請參閱 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 預設內容 (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 物件)。
除了此處指定的標籤外,還會將一個設為 visual-studio-codecom.microsoft.created-by 標籤新增至映像檔。此行為可透過將 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_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 [ARG...]
containerName 賦予已啟動容器的名稱。
必要項,除非從平台推斷得出。
--name
環境變數 在容器中設定的環境變數。這是一個鍵值對清單。 -e--env
envFiles 這是一個 .env 檔案清單。 --env-file
labels 賦予已啟動容器的標籤。這是一個鍵值對清單。 --label
network 容器將連接到的網路名稱。 --network
networkAlias 已啟動容器的網路範圍別名。 --network-alias
os 預設為 Linux,另一個選項為 Windows。這是使用的容器作業系統。 不適用 (N/A)
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 工作)

屬性 說明 預設值
引數 傳遞給 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>
環境檔案 讀取並套用於容器的環境變數檔案。 --env-file <file>
projectName 命名與標記 Docker 物件時使用的替代專案名稱。若在進行 compose up 時使用替代專案名稱,則在 compose down 時必須指定相同的專案名稱。 --project-name <name>

up 物件屬性

屬性 說明 CLI 對等指令 預設值
detached 是否以分離模式執行。 -d true
build 執行前是否先建置。 --build true
scale 每個服務要執行的執行個體數量。這是一個鍵值對清單。 --scale SERVICE=NUM
services 要啟動服務的子集。不能與 profiles 結合使用。 [SERVICE...] (全部)
profiles 要啟動設定檔 (profiles) 的子集。不能與 services 結合使用。 --profile <profile> (全部)
customOptions up 引數之後新增的任何額外參數。不會嘗試解決與其他選項的衝突,也不會驗證此選項。 (任意)

down 物件屬性

屬性 說明 CLI 對等指令 預設值
removeImages 是否移除映像檔,以及移除哪些。all 將移除任何服務所使用的所有映像檔,local 將僅移除無自訂標籤的映像檔。若不設定此項,將不會移除任何映像檔。 --rmi
removeVolumes 是否移除已命名的磁碟區。 -v false
customOptions down 引數之後新增的任何額外參數。不會嘗試解決與其他選項的衝突,也不會驗證此選項。 (任意)

指令自訂

當您執行各種操作時,Container Tools 擴充功能會執行許多 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 Build

配置設定 預設值
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 Run

配置設定 預設值
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 規則運算式將與所選映像檔的完整標籤進行比較。

Container Attach

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

支援的權杖

權杖 說明
${containerCommand} 用於執行容器指令的 CLI 指令 / 可執行檔。
${containerId} 要附加之容器的 ID。
${shellCommand} 若容器中存在 bash,則會在此處替換為 bash,否則為 sh。在 Windows 容器中,一律使用 cmd

注意match 規則運算式將與容器名稱及容器映像檔的完整標籤進行比較。

Container Logs

配置設定 預設值
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} 指令的字串傳回值。
© . This site is unofficial and not affiliated with Microsoft.