通过

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

为开发箱编写自定义文件

  • 项目

本文介绍如何使用 Visual Studio Code (VS Code) 和开发人员主页为开发箱创建和测试自定义文件。

可通过两种方式在 Microsoft Dev Box 中使用自定义文件。 当开发人员在池上配置团队自定义时，系统会自动应用这些设置。 当用户创建开发箱时，会应用个人自定义设置。

本文帮助你在自定义文件中定义新任务，将其应用到开发箱，并在 VS Code 中直接测试这些自定义设置。

重要

Dev Box 团队自定义功能目前以预览版提供。 有关预览版状态的详细信息，请参阅 Microsoft Azure 预览版的补充使用条款。 该文档定义了适用于测试版、预览版或尚未正式发布的 Azure 功能的法律术语。

先决条件

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

配置自定义所需的权限

若要执行所需的操作来为开发箱创建和应用自定义设置，需要拥有以下权限：

操作 权限/角色
为开发人员中心启用项目级目录。 对订阅拥有写入访问权限的平台工程师。
为项目启用目录同步设置。 对订阅拥有写入访问权限的平台工程师。
将目录附加到项目中。 项目的项目管理员或参与者权限。
创建自定义文件。 未指定。 任何人都可以创建自定义文件。
在开发箱创建过程中，使用开发人员门户上传和应用 YAML 文件。 Dev Box 用户。
将任务添加到目录。 添加到托管目录的存储库的权限。

什么是自定义文件？

Dev Box 自定义功能使用 yaml 格式化文件来指定开发人员创建开发箱时要应用的任务列表。 这些任务可以像安装包一样简单，也可以像运行一组复杂的脚本来设置基本代码一样复杂。 任务可标识目录并提供要安装的软件的名称等参数。 然后，创建开发箱的开发人员可以使用该自定义文件。

以下示例使用 winget 任务来安装 VS Code，并使用 git-clone 任务克隆存储库：

# From https://github.com/microsoft/devcenter-examples
$schema: 1.0
tasks:
  - name: winget
    parameters:
      package: Microsoft.VisualStudioCode
      runAsUser: true
  - name: git-clone
    description: Clone this repository into C:\Workspaces
    parameters:
      repositoryUrl: https://github.com/OrchardCMS/OrchardCore.git
      directory: C:\Workspaces

有两种方法来使用自定义文件：单个自定义（适用于单个开发箱）和团队自定义（适用于整个团队）。

单个自定义文件

  • 包含开发人员创建开发箱时要应用的任务。
  • 由开发人员在创建开发箱期间上传。

团队自定义文件

  • 包含开发人员创建开发箱时要应用的任务。
  • 跨团队或项目共享。
  • 包括一个指定基本映像的字段。
  • 名称为 imagedefinition.yaml。
  • 上传到托管目录的存储库。
  • 当开发人员从配置的池创建开发箱时自动使用。

重要

映像定义只能使用 Dev Box 市场映像作为基础映像。 若要获取开发人员中心可访问的映像列表，请使用以下 Azure CLI 命令：

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

创建自定义文件

可以使用 VS Code 创建和管理自定义文件。 可以使用 VS Code 中的 Microsoft Dev Box 扩展来发现附加目录中的任务和测试自定义文件。

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

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

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

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

    Visual Studio Code 中 Dev Box 命令面板的屏幕截图，其中显示了“列出可用任务”的命令。

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

    Visual Studio Code 中的 Dev Box 命令面板的屏幕截图，其中显示了“应用自定义任务”的命令。

  6. 自定义文件会立即运行，并将指定的任务应用于测试开发箱。 检查更改并检查 VS Code 终端，看看任务执行期间是否生成了任何错误或警告。

  7. 自定义文件成功运行后，将其上传到目录。

使用自定义文件克隆专用存储库

可以在 YAML 自定义设置中使用 Azure Key Vault 中的机密来克隆专用存储库，也可使用你创作的任何需要访问令牌的自定义任务。 在团队自定义文件中，可以使用密钥保管库中存储的个人访问令牌 (PAT) 来访问专用存储库。

在团队自定义文件中使用 Key Vault 机密

若要克隆专用存储库，请将 PAT 存储为 KeyVault 机密，并在自定义设置中调用 git-clone 任务时使用它。

若要配置 Key Vault 机密以便在 YAML 自定义中使用，请执行以下操作：

  1. 请确保你的开发人员中心项目的托管标识在密钥保管库上具有 Key Vault 读取者角色和 Key Vault 机密用户角色。
  2. 向应在开发箱自定义期间使用机密的每个用户或用户组授予 Key Vault 机密的 Key Vault 机密用户角色。 授予该角色的用户或组必须包括开发人员中心的托管标识、你自己的用户帐户，以及开发箱自定义期间需要机密的任何用户或组。

有关详细信息，请参阅：

可按以下格式引用 YAML 自定义设置中的机密，以 git-clone 任务为例：

$schema: "1.0"
tasks:
   name: git-clone
   description: Clone this repository into C:\Workspaces
      parameters:
         repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
         directory: C:\Workspaces
         pat: '{{KEY_VAULT_SECRET_URI}}'

在单个自定义文件中使用 Key Vault 机密

如果你想要从单个自定义文件中克隆专用 Azure Repos 存储库，无需在 Azure Key Vault 中配置机密。 相反，可以使用 {{ado}} 或 {{ado://your-ado-organization-name}} 作为参数。 当你创建开发箱时，此参数将代表你提取访问令牌。 该访问令牌对存储库具有只读权限。

快速入门目录中的 git-clone 任务使用访问令牌克隆你的存储库。 下面是一个示例：

tasks:
   name: git-clone
   description: Clone this repository into C:\Workspaces
      parameters:
         repositoryUrl: https://myazdo.visualstudio.com/MyProject/_git/myrepo
         directory: C:\Workspaces
         pat: '{{ado://YOUR_ADO_ORG}}'

开发人员中心需要访问你的密钥保管库。 开发人员中心不支持服务标记，因此如果 Key Vault 保持专用，则你必须允许受信任的 Microsoft 服务绕过防火墙。

该屏幕截图显示允许受信任的 Microsoft 服务绕过 Azure Key Vault 设置中的防火墙的选项。

若要了解如何允许受信任的 Microsoft 服务绕过防火墙，请参阅配置 Azure Key Vault 网络设置。

使用现有的 WinGet 配置文件自定义开发箱

WinGet 配置采用配置即代码方法来定义所需的软件和配置设置集，以将 Windows 环境设为编码就绪状态。 还可以使用这些配置文件来设置开发箱，方法是使用 Microsoft 提供的快速入门目录中包含的 WinGet 任务。

以下示例演示了调用现有 WinGet Desired State Configuration (DSC) 文件的开发箱自定义文件：

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

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

从代码存储库共享自定义文件

通过将自定义文件命名为 imagedefinition.yaml 并将其上传到托管目录的存储库，使该文件可供开发箱池使用。 创建开发箱池时，可以从目录中选择要应用于池中的开发箱的自定义文件。

相关内容