如何创作 WinGet 配置文件

2025-06-11

若要创建 WinGet 配置文件，请执行以下作：

按照 WinGet 配置文件命名约定创建 YAML 文件。
熟悉 WinGet 配置文件的格式，并链接当前文件架构。
确定断言列表（必需先决条件）和资源（所需的安装和设置配置列表，使计算机的开发环境达到所需状态）以包含在文件中。
确定完成所需配置任务所需的 PowerShell 模块和 Desired State Configuration （DSC）资源。
确定每个配置资源所需的指令和设置。
确定每个资源的依赖项。

文件格式

Windows 程序包管理器使用清单（YAML 文件）来查找和安装 Windows 用户的包。 WinGet 配置文件使用相同的 YAML 样式格式，添加 JSON 架构规范来帮助定义文件的结构和验证。为了进一步帮助检测 WinGet 配置文件的格式是否有效，我们建议将 Visual Studio Code 与 RedHat 的 YAML 扩展配合使用以支持正确的语法，帮助检测任何格式错误，提供悬停支持和自动完成（链接到 JSON 架构文件时），并确保有效的格式设置。

文件命名约定

命名 WinGet 配置文件的约定是使用“.winget”文件扩展名（如 configuration.winget）。对于基于 Git 的项目，默认配置应存储在以下位置的“.config”目录中。 ./config/configuration.winget 在某些情况下，可能会因为不同的工具链或用户偏好而适用多个配置文件。其他配置文件还应位于“.config”目录中。

WinGet 配置文件的各个部分

WinGet 配置文件分为两个主要部分：

断言：运行配置所需的先决条件。
资源：要安装的软件和工具列表、这些安装的配置设置以及 Windows作系统的配置设置。

断言部分

断言列表涵盖此 WinGet 配置文件中列出的资源在运行该文件的计算机上成功所需的先决条件（或先决条件）。断言可以并行完成，不需要任何顺序。

示例断言：

OS 版本：计算机上安装的作系统的最低版本* 。随着功能随时间推移添加到 OS，一些功能会向后移植以支持早期版本，有些则不支持。始终检查最低操作系统版本来确定是否支持配置所需的特定工具或功能，这很有帮助。例如，WinGet（Windows 包管理器）要求至少需要 Windows 10 版本 1809 或更高版本。任何较旧版本的 Windows 都不支持 WinGet。 * PowerShell DSC 资源可以更改系统状态，但在开源项目的项目配置中调用 Windows 更新并修改操作系统版本是不合适的。

如果断言返回“false”以指示系统未达到所需状态，那么任何使用字段将该断言标识为依赖项的 dependsOn 都将被跳过，无法运行。在这种情况下，即使未对 Windows 环境应用任何配置更改，此配置也会被视为成功结果。

“资源”部分

资源列表涵盖需要安装的所有软件、工具、包等，以及 Windows作系统或已安装应用程序的配置设置。需要为每个资源指定一个名称、要执行的指令说明以及负责执行该指令以及任何关联的设置或依赖项的 PowerShell 模块。

WinGet 配置文件示例

下面是 WinGet 格式化配置文件 configuration.winget 的示例：

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
properties:
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement
        allowPrerelease: true
      settings:
        MinVersion: '10.0.22000'
  resources:
    - resource: Microsoft.Windows.Settings/WindowsSettings
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
        securityContext: elevated
      settings:
        DeveloperMode: true
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        securityContext: elevated
      settings:
        id: Microsoft.VisualStudio.2022.Community
        source: winget
    - resource: Microsoft.VisualStudio.DSC/VSComponents
      dependsOn:
        - vsPackage
      directives:
        description: Install required VS workloads from vsconfig file
        allowPrerelease: true
        securityContext: elevated
      settings:
        productId: Microsoft.VisualStudio.Product.Community
        channelId: VisualStudio.17.Release
        vsConfigFile: '${WinGetConfigRoot}\..\.vsconfig'
        includeRecommended: true
  configurationVersion: 0.2.0

此文件的组件包括：

架构：您的配置文件中的第一行应包含以下注释：# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/<most recent schema version #> 以说明文件所遵循的 DSC 架构。若要查找最新版本的 WinGet 配置架构，请转到 https://aka.ms/configuration-dsc-schema/。此示例时的最新架构编号为0.2，因此架构输入为： # yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2
属性：配置文件的根节点必须 properties 包含配置版本（configurationVersion: 0.2.0 在此示例中）。此版本应根据配置文件的更新进行更新。属性节点应包含节点 assertions 和 resources 节点。
断言：列出本部分中此配置所需的先决条件（或先决条件）。
资源：assertions 和 resources 列表部分都由表示设置任务的单个 resource 节点组成。应为 resource 指定 PowerShell 模块的名称，并接着指定该模块中将被调用以应用所需状态的 DSC 资源的名称：{ModuleName}/{DscResource}。每个资源必须包括 directives 和 settings。还可以选择性地包含一个id值。应用配置时，WinGet 将知道从 PowerShell 库安装模块并调用指定的 DSC 资源。
指令：本节 directives 提供有关模块和资源的信息。本部分应包含一个 description 值，用于描述模块正在完成的配置任务。通过 allowPrerelease 值，您可以选择是否允许配置 (true) 使用来自 PowerShell 画廊的“预发布”模块。某些 DSC 资源可能需要使用管理员权限运行。资源 securityContext: elevated 指令部分下的字段指示此要求。设置为 elevated 时，WinGet 将在配置开始时提示进行一次 UAC 审批。然后，WinGet 将启动两个进程：一个使用提升的权限运行资源，另一个进程运行具有当前用户权限的资源。
设置：资源 settings 值表示要传递给 PowerShell DSC 资源的名称/值对的集合。设置可以表示是否启用开发人员模式、应用正则密钥或建立特定网络设置的任何内容。
依赖项：资源的 dependsOn 值确定在开始此任务之前是否必须完成任何其他的断言或资源。如果依赖项失败，此资源也会自动失败。
ID：特定资源实例的唯一标识符。如果另一个资源依赖于该资源先被应用，则可以使用id值。

组织“资源”部分

确定如何组织 WinGet 配置文件的“资源”部分时，需要考虑多种方法。可以通过以下方式组织文件列表：

执行顺序：根据应执行资源的逻辑顺序组织资源列表。此方法可帮助用户了解并遵循文件运行后执行的自动化步骤——首先安装什么，其次安装什么，第三步更新哪个设置，等等。
失败的可能性：根据潜在故障的可能性组织资源列表可以帮助用户提前捕获配置过程中的问题，并帮助他们了解剩余步骤可能失败的原因，使他们能够在投入大量时间之前识别和进行必要的更改。
分组类似的资源类型：通过将类似的资源类型组合在一起来组织资源列表是软件工程方法中的一种常见方法，可能是你或使用配置文件的其他开发人员最熟悉的方法。

建议将 README.md 文件包含在包含文件结构的组织方法的任何开放源代码发布的 WinGet 配置文件中。

使用变量 ${WinGetConfigRoot}

某些 DSC 资源可能会采用指定文件路径的参数。在不指定完整路径的情况下，您可以使用变量 ${WinGetConfigRoot} 来定义执行 winget configure 命令的工作目录，并通过追加相对路径指向该文件。这可用于通用化配置文件，使其与计算机无关。 Microsoft.VisualStudio.DSC/VSComponents上面的示例中的资源通过使用${WinGetConfigRoot}指向项目的根目录中的 .vsconfig 文件来展示此功能。这也意味着在执行 winget configure 命令之前，用户应确保目标文件位于基于当前工作目录的相对路径中。

在何处查找 PowerShell DSC 资源模块

查看 Microsoft 支持的“PowerShell Desired State Configuration”随时可用（“收件箱”）资源列表，包括：

环境：管理计算机或进程的环境变量。
MsiPackage：安装或卸载 MSI 包。
注册表：管理注册表项或值。
脚本：运行 PowerShell 脚本块。
服务：管理 Windows 服务。
WindowsFeature：安装或卸载 Windows 角色或功能。
WindowsProcess：启动或停止 Windows 进程。

还可以在 PowerShell 库中找到 PowerShell DSC 资源模块。此画廊托管着数百个 PowerShell 模块，其中包含用户社区提交的 Desired State Configuration (DSC) 资源。可以通过在“类别”下应用“DSC 资源”筛选器来筛选搜索结果。这个存储库 未由Microsoft 验证，并包含来自各种作者和发布者的资源。在使用 PowerShell 模块之前，应始终检查其安全性和可信度，因为任何任意的脚本都可能被包括在内。有关如何创建可信 WinGet 配置文件的更多提示，请参阅如何检查 WinGet 配置文件的可信度。

通过