你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

自定义架构参考

Microsoft Dev Box 的自定义功能允许平台工程师和开发者预装工具、克隆仓库，并通过使用 YAML 文件在开发者机器上配置设置。本参考描述了当前 YAML 文件和 Dev Box 自定义支持的内置任务的模式。

当你需要时使用这个参考资料：

查找 imagedefinition.yaml 或 task.yaml 文件中有效的属性、类型和默认值。
确认内置 ~/gitclone、 ~/powershell和 ~/winget 任务接受的参数。
理解、、、 variables和 buildProperties 在开发 Box 配置镜像或应用自定义时如何tasksparameters协同工作。 userTasks

自定义文件类型

Dev Box 自定义使用三种 YAML 文件类型，每种都有不同的用途和受众：

文件	Purpose	作者	运行位置
`imagedefinition.yaml`	定义了开发机池的可重用镜像。列出基础镜像、参数、变量、系统任务、用户任务和构建属性，供 Dev Box 创建镜像定义时应用。	平台工程师或团队负责人	存放在附带项目目录中;应用到每个从引用镜像定义的池创建的开发者盒子上。
`task.yaml`	定义了一个可重用、参数化的自定义任务，添加到目录中。允许管理员用元数据、参数验证、文档和执行设置包裹PowerShell逻辑。	平台工程师	存储在附属于开发中心的目录中;通过OR FILES`devbox.yaml`的名称`imagedefinition.yaml`呼叫。
`devbox.yaml`	个人用户自定义文件在开发者盒创建过程中上传。只适用于它连接的开发机。	个人开发者	从本地磁盘上传，或从开发者门户的仓库引用。

内置 ~/gitclone、 ~/powershell和 ~/winget 任务都可以在任何开发中心获得，无需附带目录。要添加自定义任务，可以在目录文件中定义它们 task.yaml ，并从你的图像定义或用户自定义文件中按名称调用。欲了解更多信息，请参见 Microsoft Dev Box 自定义。

Imagedefinition.yaml 文件

用于 imagedefinition.yaml 定义 Dev Box 在创建图像定义时应用的图像、参数、变量和自定义任务。

示例 imagedefinition.yaml 文件

$schema: "1.0"
name: example-image-definition
description: Install core tools and clone the project repository.
image: microsoftvisualstudio_visualstudioplustools_vs-2022-ent-general-win11-m365-gen2
parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.
variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.
tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces
      branch: "{{repositoryBranch}}"
userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo
buildProperties:
  networkConnection: corp-westus3

Imagedefinition.yaml 属性

资产	必填	类型	说明
$schema		字符串或数字	指定文件的模式版本。
name	✅	字符串	定义了图像定义的友好名称。
description		字符串	描述图像定义。
image	✅	字符串	识别用于开发商盒映像的基础镜像。
参数		对象	定义任务可在图像定义中引用的输入参数。
variables		对象	定义图像定义的可重复使用值。
任务		任务对象数组	列出在配置过程中需要执行的系统上下文自定义任务。
用户任务		任务对象数组	列出登录后需要执行的用户上下文自定义任务。
buildProperties（buildProperties）		对象	定义了针对图像创建的具体配置。

`$schema`

（字符串或数字）

指定文件的模式版本。当前的例子使用 1.0。

$schema: "1.0"

`name`

（字符串，必填，3-63字符）

指定你选择图片定义时显示的友好名称。此设置控制创建和更新池时可用的映像定义的名称。名称不能包含 /， "， [， @<|>:+?;=*,&]空白，或以 _ 或 -开头。

name: example-image-definition

`description`

（弦乐）

描述图像定义的目的。

description: Install core tools and clone the project repository.

`image`

（字符串，必填）

指定用于开发盒镜像的基础镜像。该图片可以是市场图片，也可以是附加的 Azure 计算图库中的自定义图片，格式为 gallery-name/image-name@version。

示例：

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

image: my-gallery/[email protected]

要附加 Azure 计算画廊，请参见“配置 Microsoft Dev Box 的 Azure 计算画廊。

要获取开发中心可访问的镜像列表，可以使用 Azure CLI：

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

如有需要，先安装开发中心 Azure CLI 扩展：

az extension add --name devcenter

`parameters`

（物体）

定义了命名输入参数，你可以用 {{parameterName}} 语法在任务中引用。

parameters:
  repositoryBranch:
    type: string
    default: main
    description: Branch to clone during setup.

参数对象属性

资产	必填	类型	说明
类型	✅	字符串	指定参数数据类型。
允许		字符串数组	将参数限制为固定的字符串值列表。
default	✅	字符串、布尔值或数字	设置参数的默认值。
description		字符串	描述参数。
验证正则表达		字符串	验证字符串值与正则表达式的关系。
minLength		整数	设定字符串值的最小长度。
maxLength		整数	设定字符串值的最大长度。

`type`

（字符串，必修，允许的值：字符串、布尔值、数字）

指定参数数据类型。

`allowed`

（字符串数组）

限制参数为一组固定允许的字符串值。

`default`

（字符串、布尔值或数字，需）

设置参数的默认值。

`description`

（弦乐）

描述作者和工具参数。

`validationRegex`

（弦乐）

定义字符串值必须匹配的正则表达式。

`minLength`

（整数）

设定字符串值的最小长度。

`maxLength`

（整数）

设定字符串值的最大长度。

`variables`

（物体）

定义了可以在图像定义中重复使用的命名变量。

variables:
  workspaceRoot:
    type: string
    value: C:\Workspaces
    description: Root directory for repositories.

变量对象属性

资产	必填	类型	说明
类型	✅	字符串	指定变量数据类型。
价值	✅	字符串、布尔值或数字	设置变量值。
description		字符串	描述变量。

`type`

（字符串，必修，允许的值：字符串、布尔值、数字）

指定变量数据类型。

`value`

（字符串、布尔值或数字，需）

设置变量值。

`description`

（弦乐）

描述了作者和工具的变量。

`tasks`

（任务对象数组）

列出在配置过程中系统环境中运行的自定义任务。你提供的具体输入值会根据任务而异。每个任务条目必须包含 name ，并且也可以定义 displayName、 description、 parameters、和 timeout。

tasks:
  - name: ~/winget
    parameters:
      package: Git.Git
  - name: ~/gitclone
    timeout: 1800
    parameters:
      repositoryUrl: https://github.com/example-org/example-repo.git
      directory: C:\Workspaces

该 timeout 属性是可选的，使用 imagedefinition.yaml时以秒为单位。

tasks:
  - name: ~/powershell
    timeout: 1800
    parameters:
      command: <command>

任务输入属性

资产	必填	类型	说明
name	✅	字符串	识别要调用的任务。
displayName		字符串	为任务提供简短的界面文本。
description		字符串	描述任务的具体内容。
参数		对象	提供任务的输入值。
timeout		整数	覆盖任务执行时间，只需几秒。

`name`

（字符串，必填）

识别要执行的任务。对于内置任务~/winget，如、 ~/powershell和 ~/gitclone，使用前缀。~/

`displayName`

（弦乐）

为界面表面提供简短的显示文本。

`description`

（弦乐）

描述任务在图像定义中的作用。

`parameters`

（物体）

定义传递给任务的输入值。参数名称和值类型取决于所选任务。

参数定义遵循与参数属性相同的 task.yaml 模式。详情请参见 type， allowed， validationRegexdescriptionminLengthdefaultmaxLength和。required

`timeout`

（整数）

在几秒内覆盖任务执行超时。

`userTasks`

（任务对象数组）

列出登录后用户上下文中可执行的自定义任务。 userTasks 使用与 tasks相同的任务输入模式。

userTasks:
  - name: ~/powershell
    parameters:
      command: code C:\Workspaces\example-repo

`buildProperties`

（物体）

定义了针对构建的具体设置，以自定义图像构建过程。

buildProperties:
  networkConnection: corp-westus3

构建属性对象属性

资产	必填	类型	说明
网络连接		字符串	选择用于镜像构建的网络连接。

`networkConnection`

（弦乐）

指定图像创建时使用的网络连接方式。当构建任务需要访问资源，如私有仓库或存储账户，这些资源只能通过特定网络连接访问时，可以使用此设置。网络连接必须连接到开发中心，才能用它来创建镜像。

buildProperties:
  networkConnection: my-westus3

内置任务

当你需要常用的自定义操作时，使用内置任务，无需附加目录。使用 ~/ 前缀调用内置任务，例如 ~/winget，， ~/powershell或 ~/gitclone。

GitClone 内置任务
PowerShell 内置任务
WinGet 内置任务

GitClone 内置任务

使用GitClone内置任务将仓库克隆到开发框中。

示例：

tasks:
  - name: ~/gitclone
    parameters:
      repositoryUrl: https://github.com/microsoft/calculator
      directory: C:\Workspaces
      branch: main

资产	必填	类型	说明
repositoryUrl	✅	字符串	指定要克隆的仓库URL。
目录		字符串	设置存储库克隆的目录。
分支		字符串	选择一个分支进行克隆。
帕特		字符串	为认证克隆操作提供个人访问令牌。

`repositoryUrl`

（字符串，必填）

指定要克隆的仓库URL。

`directory`

（字符串，默认：C：\Workspaces）

设置存储库克隆的目录。

`branch`

（弦乐）

选择一个分支进行克隆。

`pat`

（弦乐）

为认证克隆操作提供个人访问令牌。如果 pat 没有提供，克隆会排队等待首次用户登录。当你提供 pat时，任务可以在配置过程中克隆。使用密钥保管库的秘密引用代替原始的秘密值。

GitClone 内置任务在执行时还会安装 PowerShell 7、Git 和 Git LFS。

PowerShell 内置任务

使用PowerShell内置任务来运行命令或脚本。

示例：

tasks:
  - name: ~/powershell
    parameters:
      command: Write-Host "Hello from Dev Box"

资产	类型	说明
command	字符串	运行一个内联指令。
工作目录	字符串	设置命令或脚本的工作目录。
脚本	字符串	运行本地或远程的PowerShell脚本。
scriptArgs	字符串	为剧本提供了论据。
scriptExecutionPolicy	字符串	为脚本设定执行策略。

`command`

（弦乐）

运行一个内联指令。如果你提供 command， script则忽略了、 scriptArgs和 scriptExecutionPolicy 参数。

`workingDirectory`

（弦乐）

设置命令或脚本的工作目录。

`script`

（弦乐）

指定运行到本地或远程PowerShell脚本的路径。当 command 提供时，该参数被忽略。

`scriptArgs`

（弦乐）

为剧本提供了论据。当 command 提供时，该参数被忽略。

`scriptExecutionPolicy`

（字符串，默认：绕过）

为脚本设定执行策略。当 command 提供时，该参数被忽略。

WinGet 内置任务

使用WinGet内置任务直接安装包或应用WinGet配置文件。

重要

WinGet 内置任务和可执行文件是不一样 winget 的。内置任务使用 PowerShell WinGet cmdlet。

示例：

tasks:
  - name: ~/winget
    parameters:
      package: GitHub.GitHubDesktop
      version: 3.4.16

资产	类型	说明
配置文件	字符串	指向本地的WinGet配置文件。
下载网址	字符串	从公共网址下载配置文件。
inlineConfigurationBase64	字符串	提供一个基于Base64编码的WinGet配置文件。
软件包	字符串	直接按名称安装一个包。
version	字符串	安装特定的软件包版本。

`configurationFile`

（弦乐）

指向本地机器上的WinGet配置YAML文件。

`downloadUrl`

（弦乐）

为WinGet配置的YAML文件指定一个公共URL。文件被下载到路径中 configurationFile。

`inlineConfigurationBase64`

（弦乐）

提供一个基于Base64编码的WinGet配置YAML文件。任务会将其解码为 configurationFile，或者如果 configurationFile 没有设置，则将其解码为临时文件。

`package`

（弦乐）

直接按名称安装一个包。如果你使用配置文件源，就不需要提供 package。

`version`

（弦乐）

安装特定的软件包版本。如果你使用配置文件源，就不需要提供 version。

task.yaml 文件

用于 task.yaml 定义目录中的可重复使用自定义任务。任务定义描述了任务的命令、元数据、参数、文档和执行设置。

当你定义自定义任务时，你会确定哪些任务是开发 imagedefinition.yaml 者可以在文件中使用 devbox.yaml 的。你可以用任务定义来限制高权限操作，比如执行任意PowerShell命令的能力。

示例 task.yaml 文件

$schema: "1.0"
name: install-vsix-extension
description: Install a Visual Studio extension from a VSIX package.
author: Contoso Corporation
command: .\install-extension.ps1 -VsixPath {{vsixPath}}
documentationURL: https://contoso.example/devbox/install-vsix-extension
keywords:
  - visual-studio
  - extension
parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.
timeout: 30
rebootRequired: false
documentation:
  notes: Use a path that is available during task execution.
  examples:
    - name: install-vsix-extension
      parameters:
        vsixPath: .\extensions\contoso.vsix

以下示例展示了在特定工作目录中运行PowerShell命令的任务定义：

$schema: "1.0"
name: powershell
description: Execute a PowerShell command.
author: Microsoft Corporation
command: .\runcommand.ps1 -command {{command}} -workingDirectory {{workingDirectory}}
parameters:
  command:
    type: string
    default: ""
    required: true
    description: The command to execute.
  workingDirectory:
    type: string
    default: ""
    required: false
    description: The working directory in which to execute the command.

Task.yaml 属性

资产	必填	类型	说明
$schema	✅	字符串	指定任务文件的模式版本。
name	✅	字符串	定义任务标识符。
command	✅	字符串	提供实现该任务的PowerShell命令。
description		字符串	描述任务。
作者		字符串	识别任务作者。
问题通知邮件		字符串	提供任务问题的联系邮箱。
文档网址		字符串	任务文档链接。
许可证网址		字符串	任务许可证链接。
关键字		字符串数组	列出任务的关键词。
参数		对象	定义任务接受的输入。
timeout		整数	默认超时时间为几分钟。
文档		对象	为用户添加备注和任务调用示例。
重启需求		布尔	指示任务执行后是否需要重启。

`$schema`

（字符串，必填）

指定任务定义的模式版本。当前的例子使用 1.0。

`name`

（字符串，必填）

定义用于引用任务的imagedefinition.yamldevbox.yaml标识符。该名称在任务所在的目录上下文中必须是唯一的。

使用与其他 Dev Box 自定义工件相同的命名约束。名称必须在3到63个字符之间，以字母数字字符开头，且仅包含字母数字字符、 -、 .或 _。保留 / 字符。

name: install-vsix-extension

`command`

（字符串，必填）

指定实现该任务的PowerShell命令。该命令在本地机器的 Windows PowerShell 中运行。使用 {{parameterName}} 语法来引用命令字符串中的参数值。

command: .\install-extension.ps1 -VsixPath {{vsixPath}}

例如：

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

`description`

（弦乐）

描述任务的目的。

description: This task executes a PowerShell command.

`author`

（弦乐）

识别任务作者进行审计和故障排除。

author: Contoso Corporation

`issueNotificationEmail`

（弦乐）

提供一个电子邮件地址，用户在任务中遇到问题时可以联系。产品功能不会消耗这种价值。

`documentationURL`

（弦乐）

任务文档链接。

documentationURL: https://link.to/documentation

`licenseURL`

（弦乐）

任务许可证链接。

licenseURL: https://link.to/license

`keywords`

（字符串数组）

列出帮助消费者找到任务的关键词。

`parameters`

（物体）

为任务定义了命名的输入参数。每个子项代表一个参数名称，可以定义参数类型、允许值、默认值、描述、验证规则、长度限制以及是否需要该参数。

parameters:
  vsixPath:
    type: string
    required: true
    description: Path to the VSIX package.

参数定义性质

资产	必填	类型	说明
类型	✅	字符串	指定输入数据类型。
允许		字符串数组	限制输入为固定字符串值列表。
default		字符串、布尔值或数字	设置输入的默认值。
description		字符串	描述输入。
验证正则表达		字符串	验证字符串值与正则表达式的关系。
minLength		整数	设定字符串值的最小长度。
maxLength		整数	设定字符串值的最大长度。
required		布尔	表示是否必须提供输入。

`type`

（字符串，必修，允许的值：字符串、布尔值、数字）

指定输入数据类型。

`allowed`

（字符串数组）

限制输入只能使用一组固定的允许字符串值。

`default`

（字符串、布尔值或数字）

设置输入的默认值。

`description`

（弦乐）

描述输入。

`validationRegex`

（弦乐）

定义字符串值必须匹配的正则表达式。

`minLength`

（整数）

设定字符串值的最小长度。

`maxLength`

（整数）

设定字符串值的最大长度。

`required`

（布尔值）

表示是否必须提供输入。如果省略，则默认为 false。

`timeout`

（整数，默认：30）

默认任务超时时间为几分钟。如果你不指定数值，默认是30分钟。

timeout: 30

`documentation`

（物体）

提供任务使用者在将任务添加到图像定义时可用的注释和调用示例。

文档对象属性

资产	必填	类型	说明
笔记：		字符串	为任务的使用者提供指导。
示例		任务对象数组	展示了如何从 YAML 文件调用任务。

`notes`

（弦乐）

为任务使用者提供指导或注意事项。

`examples`

（任务对象数组）

通过使用与任务条目的 imagedefinition.yaml相同模式，展示任务调用示例。

`rebootRequired`

（布尔值，默认：false）

指示任务执行后是否需要重启。

配置团队自定义 ——创建 imagedefinition.yaml 文件并将其应用到开发机池。
为你的开发机配置一个用户自定义文件 ——作者并上传个人 devbox.yaml 文件。
配置 Dev Box 自定义任务 ——作者 task.yaml 文件并通过目录发布。
连接到 Azure 资源或克隆专用存储库

反馈

此页面是否有帮助？

Last updated on 2026-07-01

自定义架构参考

自定义文件类型

Imagedefinition.yaml 文件

示例 imagedefinition.yaml 文件

Imagedefinition.yaml 属性

$schema

name

description

image

parameters

参数对象属性

type

allowed

default

description

validationRegex

minLength

maxLength

variables

变量对象属性

type

value

description

tasks

任务输入属性

name

displayName

description

parameters

timeout

userTasks

buildProperties

构建属性 对象属性

networkConnection

内置任务

GitClone 内置任务

repositoryUrl

directory

branch

pat

PowerShell 内置任务

command

workingDirectory

script

scriptArgs

scriptExecutionPolicy

WinGet 内置任务

configurationFile

downloadUrl

inlineConfigurationBase64

package

version

task.yaml 文件

示例 task.yaml 文件

Task.yaml 属性

$schema

name

command

description

author

issueNotificationEmail

documentationURL

licenseURL

keywords

parameters

参数定义性质

type

allowed

default

description

validationRegex

minLength

maxLength

required

timeout

documentation

文档对象属性

notes

examples

rebootRequired

`$schema`

`name`

`description`

`image`

`parameters`

`type`

`allowed`

`default`

`description`

`validationRegex`

`minLength`

`maxLength`

`variables`

`type`

`value`

`description`

`tasks`

`name`

`displayName`

`description`

`parameters`

`timeout`

`userTasks`

`buildProperties`

构建属性对象属性

`networkConnection`

`repositoryUrl`

`directory`

`branch`

`pat`

`command`

`workingDirectory`

`script`

`scriptArgs`

`scriptExecutionPolicy`

`configurationFile`

`downloadUrl`

`inlineConfigurationBase64`

`package`

`version`

`$schema`

`name`

`command`

`description`

`author`

`issueNotificationEmail`

`documentationURL`

`licenseURL`

`keywords`

`parameters`

`type`

`allowed`

`default`

`description`

`validationRegex`

`minLength`

`maxLength`

`required`

`timeout`

`documentation`

`notes`

`examples`

`rebootRequired`