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

Dev Box 自定义功能可帮助你简化基于云的开发环境的设置。 让开发人员开始进入新项目或团队可能是一个复杂且耗时的过程。 通过定制，您可以配置搭载应用程序、工具、存储库、代码库、软件包和生成脚本的“即插即用”编码工作站。 本文指导你完成使用 Visual Studio Code（VS Code）为开发框创建、测试和编辑图像定义文件的过程。

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

先决条件

若要完成本文中的步骤，你必须：

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

配置自定义所需的权限

为自定义任务选择源

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

• 使用 WinGet 和 PowerShell 内置任务 Dev Box 开发中心现已支持 PowerShell 和 WinGet 任务，可以开始使用这些内置任务。 如果自定义项只需要 PowerShell 和 WinGet，请继续创建自定义文件： 创建映像定义文件。

  WinGet 内置任务不是 WinGet 可执行文件。 WinGet 内置任务基于 PowerShell WinGet CmdLet。

• 使用目录定义自定义任务 可以创建自己的自定义任务。 若要使自定义任务可供整个组织使用，请将包含自定义任务定义的目录附加到开发人员中心。 Dev Box 支持 Azure Repos 和 GitHub 目录。 由于任务只能在开发人员中心定义，因此应将任务和映像定义存储在单独的存储库中。

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

在项目级别创建映像定义

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

1.为项目管理员分配权限。

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

2. 启用项目级目录

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

1. 在 Azure 门户中，导航到开发人员中心。

2. 在左侧菜单中的 “设置”下，选择 开发人员中心设置。

3. 在 “项目”级别目录下，选择“ 为每个项目启用目录”，然后选择“ 应用”。

   

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

创建映像定义文件

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

1. 创建开发箱（或使用现有的开发箱）进行测试。

2. 在测试开发框中，安装 VS Code，然后安装 Dev Box 扩展。

3. 从示例存储库下载示例 YAML 映像定义文件，并在 VS Code 中将其打开。

4. 使用命令面板发现目录中可用的任务。 选择“视图”“命令面板”>“开发箱: 列出此开发箱的可用任务”。>

   

5. 使用命令面板在 VS Code 中测试自定义设置。 选择“视图”“命令面板”>“开发箱：应用自定义任务”>。

   

6. 映像定义文件运行并将指定的任务应用到测试开发框。 仔细检查更改，并查看 VS Code 终端，以发现任务执行过程中生成的任何错误或警告。

7. 成功运行映像定义文件时，将其上传到目录。

系统任务和用户任务

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

• 系统任务：这些任务在开发框的预配阶段作为 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 配置。

为项目配置目录同步设置

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

1. 登录到 Azure 门户。

2. 在搜索框中输入“项目”。 在结果列表中，选择“项目”。

3. 打开要为其配置目录同步设置的 Dev Box 项目。

4. 选择 Catalogs。

5. 选择“同步设置”。

   

6. 在“同步设置”窗格中，选择“映像定义”，然后选择“保存”。

   

附加包含定义文件的目录

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

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

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

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

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

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

1. 登录到 Azure 门户。

2. 在搜索框中输入“项目”。 在结果列表中，选择“项目”。

3. 打开要与新开发箱池关联的 Dev Box 项目。

4. 选择“开发箱池”，然后选择“创建”。

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

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

   

6. 选择 创建。

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

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

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

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

后续步骤

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