自訂架構參考

2025-05-29

本參考文章提供有關和檔案的詳細資訊imagedefinition.yamltask.yaml，這些檔案是用來自定義Microsoft開發方塊。開發人員可以使用這些 YAML 檔案來定義用於布建和設定開發方塊的工作。這些檔案有助於確保開發環境的一致性和效率。本文涵蓋這兩種文件類型的架構、必要屬性和範例，以及PowerShell和 WinGet等內建工作。

Imagedefinition.yaml 檔案

您可以使用 Dev Box YAML 檔案來定義在開發箱建立期間應該執行的自定義工作。檔案 devbox.yaml 可能與開發小組使用的主要來源位於相同的存放庫中，或檔案可能位於組態的集中式存放庫中。

範例映像定義 YAML：

$schema: 1.0
name: project-sample-1
image: MicrosoftWindowsDesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365
tasks:
- name: "powershell"
  inputs:
    command:

名稱

必填： 映像定義的這個易記名稱與此檔案相關聯 devbox.yaml 。此設定可控制建立和更新集區時可用的映像定義名稱。

name: myVSDevBox

圖像

必填： 您要作為映像定義基底映像的映像可以是市集映射：

image: MicrosoftWindowsDesktop_windows-ent-cpc_win11-21h2-ent-cpc-m365

或者，它可以是連結的 Azure 計算資源庫實例的自定義映射：

image: galleryname/imagename@version

若要瞭解如何將 Azure 計算資源庫實例連結至您的開發人員中心，請參閱設定適用於 Microsoft Dev Box 的 Azure 計算資源庫。

若要取得開發人員中心可存取的映像清單，請使用下列 az cli 命令：

az devcenter admin image list --dev-center-name CustomizationsImagingHQ --resource-group TeamCustomizationsImagingRG --query "[].name"

您需要開發人員中心 az cli 延伸模組：

az extension add --name devcenter

任務

必填： 此物件集合是由您布建開發方塊時要執行的 Dev Box 自定義工作所組成。提供給工作的特定輸入會因工作而異。

範例：

tasks:
- name: winget
  parameters:
    package: GitHub.GitHubDesktop

所有工作都支援 timeout 屬性，這是選擇性的。

範例：

tasks:
- name: powershell
  timeout: 1800 # in seconds
  parameters:
    command: <command>

內建工作

PowerShell 和 WinGet 可作為內建工作使用。您可以直接叫用它們，而不需在開發人員中心層級附加目錄，以定義這些工作的實作。

WinGet 內建工作

此內建工作會將 WinGet 設定套用至開發方塊。

參數：

configurationFile：
- 類型: string
- WinGet 組態 YAML 檔案的路徑。檔案必須位於本機計算機。
- 必填： false
downloadUrl：
- 類型: string
- 儲存組態 YAML 檔案的可公開存取 URL。檔案會下載至指定的路徑 configurationFile 。
- 必填： false
inlineConfigurationBase64：
- 類型: string
- WinGet 組態 YAML 檔案的Base64編碼字串。檔案會在未指定時，譯碼為指定或暫存盤的路徑 configurationFile 。
- 必填： false
package：
- 類型: string
- 要安裝的套件名稱。
- 如果在其他參數下提供組態 YAML 檔案，則不需要套件名稱。
- 必填： false
version
- 類型: string
- 要安裝的套件版本。
- 如果在其他參數下提供組態 YAML 檔案，則不需要套件版本。
- 必填： false

PowerShell 內建工作

此內建工作會執行 PowerShell 命令。

參數：

command:
- 類型: string
- 要執行的命令。
- 必填： true

task.yaml 檔案

自訂工作是可重複使用的安裝程式代碼或環境組態單位。開發人員會使用PowerShell腳本來撰寫這些腳本，並使用 task.yaml 元數據檔案來描述它們。開發人員會使用這些工作來自定義開發方塊，方法是從 devbox.yaml 檔案參考它們。

當您定義自定義工作時，您可以識別可供開發人員用於檔案的工作 devbox.yaml 。您可以限制高許可權動作，例如能夠執行任何 PowerShell 命令。

下列工作定義範例會在特定工作目錄中執行 PowerShell 命令：

name: powershell
description: Execute a powershell command
author: Microsoft Corporation
command: ".\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}"
inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute
  workingDirectory:
    type: string
    defaultValue: ""
    required: false
    description: The working directory to execute the command in

屬性

名稱

必填： 這個唯一標識碼是用來從參考工作 devbox.yaml。名稱在工作所在的目錄內容中必須是唯一的。

命名必須符合現有的 Azure 資源條件約束。名稱必須介於 3 到 63 個字元之間。它必須以英數位元開頭。名稱必須只包含英數位元和 “-”、“.” 或 “_”。保留 “/” 字元。

name: powershell

說明

自選： 此屬性描述工作。

description: This task executes a powershell command

輸入

必填： 此屬性會列出此工作作為檔案 devbox.yaml 輸入的參數，並在執行命令時使用。每個父專案都代表參數的名稱，並支援這些索引鍵：

type （必要）：此參數的輸入數據類型。可以是 string 或 int。
defaultValue （必要）：此參數採用的預設值。
required （必要）：指定此參數為選擇性或必要參數的索引鍵。
description （必要）：這個參數所代表的內容描述。

inputs:
  command:
    type: string
    defaultValue: ""
    required: true
    description: The command to execute

指令

必填： 此命令是用來完成這項工作。提供的命令字串會在本機電腦上的 Windows PowerShell 中執行。

command: ".\runcommand.ps1

命令中的參考變數

若要參考命令中的參數，請在雙括弧中指定變數名稱，例如 {{parameter_name}}。這些變數的值會在命令執行之前插入。

command: ".\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}"

超時

自選： 此變數會指定工作逾時前等候工作執行完成的時間量上限（以分鐘為單位）。預設值為30分鐘。

timeout: 30

作者

自選： 此變數會識別工作作者，以協助稽核和疑難解答。

author: Contoso Corporation

documentationURL

自選： 此變數會連結至此工作的檔。

documentationURL: "https://link.to/documentation"

licenseURL

自選： 此變數會連結至此工作的授權。

licenseURL: "https://link.to/license"

共用方式為