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

为开发框配置用户自定义

2025-07-24

可以通过上传用户自定义文件来个性化Microsoft Dev Box。用户自定义文件允许你使用首选的个人设置和应用配置开发框，以便更快地开始编码。本文介绍如何使用 Visual Studio Code 从本地驱动器或存储库创建、测试和上传用户自定义文件。你还将了解如何验证文件并管理项目的自定义设置。

通过两种方式使用 Microsoft Dev Box 中的自定义项：团队自定义项为团队创建共享配置，用户自定义项为单个开发人员创建个人配置。下表显示了两种类型的自定义项之间的差异。

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

用户自定义有助于确保开发人员遵守公司防护措施;只有通过目录预先批准的自定义任务可供开发人员在其自定义文件中使用。标准开发框用户无法在系统上下文中运行内置的 PowerShell 和 WinGet 任务，从而阻止特权升级。

可以在项目级别启用或禁用用户自定义。创建项目时，用户自定义项默认处于打开状态。

先决条件

完成本文中的步骤：

使用开发框定义、开发框池和开发框项目来设置开发中心，以便您可以创建开发框。
加入至少一个项目的 Dev Box 用户安全组。
将目录附加到开发中心，其中包含您在自定义文件中使用的任务。如果没有目录，请参阅在 GitHub 或 Azure Repos 中添加和配置目录。

设置自定义项所需的权限

若要创建自定义项并将其应用于开发框，需要以下权限：

行动	权限或角色
启用或禁用项目上的用户自定义	针对项目的写入权限。
创建自定义文件	未指定。任何人都可以创建自定义文件。
在开发框创建过程中，使用开发人员门户上传和应用 YAML 文件	开发箱用户

创建用户自定义文件

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

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

可选：使用现有的 WinGet 配置文件自定义开发框

WinGet 配置使用配置即代码方法定义使 Windows 环境准备好编码所需的唯一软件和配置设置集。还可以使用这些配置文件，通过使用微软提供的快速入门目录中包含的 WinGet 任务来设置开发环境。

此示例展示了一个开发环境自定义文件，该文件使用现有的 WinGet Desired State Configuration (DSC) 文件。

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

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

使用用户自定义文件创建开发框

使用单独的自定义文件，方法是在创建开发箱时从本地驱动器上传它，或者从存储库下载它。存储在存储库中的自定义文件必须命名为 workload.yaml。在本地存储以供上传的自定义文件应命名为 myfilename.yaml。

上传文件

在开发人员门户中，选择新建>新的开发环境。
在 “添加开发框 ”窗格中，添加开发框的详细信息。
选择 “应用自定义项”，然后选择“ 继续”。
选择上传自定义文件，选择从文件添加自定义，然后浏览并选择myfilename.yaml文件。
若要检查自定义文件中的任务是否已正确应用，请在继续作之前对其进行验证。选择“验证”。
查看开发框创建摘要，然后选择“ 创建”。

从存储库获取文件

在开发人员门户中，选择新建>新的开发环境。
在 “添加开发框 ”窗格中，添加开发框的详细信息。
选择 “应用自定义项”，然后选择“ 继续”。
选择 “上传自定义文件”，从存储库中选择 自定义文件，然后输入存储 workload.yaml 文件的存储库的 URL。
若要验证自定义文件中的任务是否已正确应用，请在继续作之前对其进行验证。选择“验证”。
查看开发框创建摘要，然后选择“ 创建”。

禁用用户自定义

用户自定义在项目级别进行控制，默认处于启用状态。可以在创建项目期间或之后禁用它们。禁用后，开发人员无法将自己的自定义文件应用到新的开发框。启用用户自定义不会绕过现有项目防护措施;开发人员只能使用附加目录中提供的任务，并且不能使用提升的权限运行任务，除非管理员已显式将管理任务包含在目录中。

目前，在为项目禁用用户自定义时，开发人员仍然可以在开发框创建过程中上传用户自定义文件。但验证过程失败，并且自定义项不会应用于开发框。

如果在禁用用户自定义项的项目中创建具有用户自定义项的开发框，将在开发人员门户中看到以下内容：

新开发框磁贴上显示一条消息，指示应用自定义项时遇到错误。
详细信息提示你与管理员联系。
开发框是在不使用用户自定义的情况下创建的。