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

为 Dev Box 团队自定义编写映像定义文件

2025-06-09

Microsoft Dev Box 自定义功能可帮助你简化基于云的开发环境的设置。让开发人员参与新项目或融入新团队常常很复杂且耗时。通过自定义配置，可以将应用程序、工具、存储库、代码库、软件包和构建脚本配置到可以直接进行编码的工作站中。本文指导你完成使用 Visual Studio Code 为开发框创建、测试和编辑图像定义文件的过程。

在 Dev Box 中使用自定义项有两种方法。 团队自定义 项为开发人员团队创建共享配置。 用户自定义 项为单个开发人员创建个人配置。下表总结了两种类型的自定义项之间的差异。

功能 / 特点	团队自定义	用户自定义
配置启用	开发箱池	开发箱
自定义应用于	池中的所有开发箱	单个开发箱
易于共享	是的	否
自定义文件名	`Imagedefinition.yaml`	`myfilename.yaml` 或 `Workload.yaml`
源自	目录	上传或从个人存储库获取
支持密钥保管库机密	是的	是的

先决条件

配置具有开发箱池和开发箱项目的开发人员中心，以便创建开发箱。
成为至少一个项目的 Dev Box 用户安全组的成员。
将目录附加到开发人员中心，其中包含可在映像定义文件中使用的任务。如果没有目录，请参阅在 GitHub 或 Azure Repos 中添加和配置目录。

配置自定义所需的权限

行动	权限/角色
为开发人员中心启用项目级目录。	对订阅拥有写入访问权限的平台工程师。
为项目启用目录同步设置。	对订阅拥有写入访问权限的平台工程师。
将目录附加到项目。	Dev Center 项目的管理员或参与者权限。
创建映像定义文件。	未指定。任何人都可以创建映像定义文件。
将任务添加到目录。	添加到托管目录的存储库的权限。

为自定义任务选择源

可以从平台内置的任务中获取 Dev Box 任务，或使用存储在目录中的自定义任务。选择最符合自定义需求和项目要求的源。

使用 WinGet 和 PowerShell 内置任务。 开发箱开发中心支持现成的 PowerShell 和 WinGet 任务。可以开始使用这些内置任务。如果自定义只需要 PowerShell 和 WinGet，请继续创建自定义配置文件。有关详细信息，请参阅创建映像定义文件。

WinGet 内置任务不是 WinGet 可执行文件。 WinGet 内置任务基于 PowerShell WinGet cmdlet。
使用目录定义自定义任务。 可以创建自己的自定义任务。若要使自定义任务可供整个组织使用，请将包含自定义任务定义的目录附加到开发人员中心。 Dev Box 支持 Azure Repos 和 GitHub 目录。由于任务仅在开发人员中心定义，因此将任务和映像定义存储在单独的存储库中。

若要详细了解如何定义自定义任务，请参阅创建 Dev Box 团队自定义任务。

在项目级别创建映像定义

项目可帮助你高效地管理 Dev Box 资源。通过为每个开发人员团队分配自己的项目，可以有效地组织资源。可以在目录存储库中创建多个映像定义，每个映像定义都位于自己的文件夹中，以针对项目下的不同开发人员团队。

为项目管理员分配权限

若要将目录附加到项目，必须具有项目的“项目管理员”或“参与者”权限。若要了解如何分配 Project Admin 权限，请参阅授予对 Dev Box 项目的管理访问权限。

启用项目级目录

必须先在开发中心级别启用项目级别目录，然后才能将目录添加到项目。在开发中心级别启用项目级别目录：

在 Azure 门户中转到你的开发人员中心。
在左侧菜单中的 “设置”下，选择 开发人员中心设置。
在 “项目”级别目录下，选择“ 为每个项目启用目录”，然后选择“ 应用”。

有关如何向项目添加目录的详细信息，请参阅从 GitHub 或 Azure Repos 添加和配置目录。

创建映像定义文件

可以使用 Visual Studio Code 创建和测试图像定义文件。除了使用内置任务之外，还可以使用 Visual Studio Code 中的 Dev Box 扩展来发现通过开发人员中心提供的自定义任务。

创建开发箱（或使用现有的开发箱）进行测试。
在测试开发框中，安装 Visual Studio Code，然后安装 Dev Box 扩展。
从示例存储库下载示例 YAML 映像定义文件。在 Visual Studio Code 中打开它。
使用命令面板发现目录中可用的任务。选择“视图”“命令面板”>“开发箱: 列出此开发箱的可用任务”。>
使用命令面板在 Visual Studio Code 中测试自定义。选择“视图”“命令面板”>“开发箱：应用自定义任务”>。
映像定义文件运行并将指定的任务应用到测试开发框。检查更改并检查 Visual Studio Code 终端，看看任务执行期间是否生成了任何错误或警告。
成功运行映像定义文件时，将其上传到目录。

系统任务和用户任务

可以在映像定义文件中同时使用系统和用户任务。映像定义文件的任务部分分为以下部分。这两个部分都基于目录中的任务定义共享相同的参数。

系统任务：在开发箱的配置阶段，这些任务以 LocalSystem 运行。它们通常用于系统级配置，例如安装软件或配置需要管理权限的系统设置。
用户任务：这些任务在用户首次登录开发框后以用户身份运行。它们通常用于用户级配置，例如安装特定于用户的应用程序或在用户上下文下配置用户设置。例如，用户通常更喜欢在用户上下文而不是系统范围内安装 Python 和 Visual Studio Code。当 WinGet 任务在 tasks 下不工作时，将它们置于 userTasks 部分中以获得更好的结果。

标准用户在配置用户自定义选项时只能使用用户任务。他们不能使用系统任务。

可选：使用现有的所需状态配置文件自定义你的开发环境

Desired State Configuration （DSC）是 PowerShell 中的一个管理平台，可用于使用配置即代码管理开发环境。可以使用 DSC 来定义开发框的所需状态，包括软件安装、配置和设置。

还可以使用 DSC 配置文件通过 WinGet 自带任务设置开发环境。

以下示例展示一个调用现有 WinGet DSC 文件的开发者框映像定义文件：

tasks:
    - name: winget
      parameters:
          configure: "projectConfiguration.dsc.yaml"

若要了解详细信息，请参阅 WinGet 配置。

为项目配置目录同步设置

将项目配置为从目录中同步映像定义。通过此设置，可以使用目录中的映像定义来创建开发箱池。

登录到 Azure 门户。
在搜索框中输入“项目”。在结果列表中，选择“项目”。
打开要为其配置目录同步设置的 Dev Box 项目。
选择 Catalogs。
选择“同步设置”。
在“同步设置”窗格中，选择“映像定义”，然后选择“保存”。

附加包含定义文件的目录

必须先将包含定义文件的目录附加到开发人员中心或项目，然后才能使用自定义文件作为映像定义。目录可以来自 GitHub 或 Azure Repos。

“映像定义”窗格列出了项目可以访问的映像定义。

有关如何附加目录的详细信息，请参阅从 GitHub 或 Azure Repos 添加和配置目录。

将开发箱池配置为使用映像定义

通过将开发箱池配置为使用自定义文件 (imagedefinition.yaml)，使自定义可供开发团队使用。将自定义文件存储在链接到开发人员中心或项目中目录的存储库中。将此文件指定为池的映像定义，自定义将应用于新的开发箱。

下面的步骤展示了如何创建开发箱池并指定映像定义：

登录到 Azure 门户。
在搜索框中输入“项目”。在结果列表中，选择“项目”。
打开要与新开发箱池关联的 Dev Box 项目。
选择“开发箱池”，然后选择“创建”。

在“创建开发箱池”页上，输入以下值：

设置	价值
名称	输入池的名称。开发人员在创建开发箱时可以选择池名称。名称在项目中必须唯一。
定义	该框列出了可访问目录中的映像定义以及开发箱定义。选择映像定义文件。
网络连接	选择“部署到 Microsoft 托管的网络”，或使用现有网络连接。
启用单一登录	选择“是”，为此池中的开发箱启用单一登录。必须为组织配置单一登录。有关详细信息，请参阅为开发箱启用单一登录。
Dev Box 创建者特权	选择“本地管理员”或“标准用户”。
启用自动停止	默认值为“是”。选择 “否 ”可禁用自动停止计划。可以在创建池后配置自动停止计划。
停止时间	选择关闭池中所有开发箱的时间。
时区	选择停止时间的时区。
许可	选中此复选框即表示确认组织具有要应用于此池中的开发箱的 Azure 混合权益许可证。

选择创建。
验证新的开发箱池是否显示在列表中。可能需要刷新屏幕。

使用开发人员门户创建开发箱

若要验证是否应用了映像定义文件中的自定义项，请在 Dev Box 开发人员门户中创建开发框。请按照快速入门：使用 Dev Box 开发人员门户创建和连接到开发框中的步骤进行操作。然后连接到新创建的开发箱，并验证自定义项是否按预期工作。

可以对自定义文件进行调整，并创建新的开发箱来测试更改。确定自定义项正确时，可以生成可重用映像。

后续步骤

现在，你有一个图像定义文件，请将其上传到目录，并将目录附加到项目。映像定义文件用于配置和创建开发团队的开发框。

为 Dev Box 团队自定义配置映像

通过