如何创作 WinGet 配置文件

项目
09/28/2023

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

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

文件格式

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

文件命名约定

命名 WinGet 配置文件的约定是 configuration.dsc.yaml。对于基于 Git 的项目，默认配置应存储在 ./configurations/configuration.dsc.yaml 的“配置”目录中。

WinGet 配置文件的部分

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

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

断言部分

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

示例断言：

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

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

资源部分

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

示例 WinGet 配置文件

下面是一个 WinGet 配置 configuration.dsc.yaml 格式化文件示例：

# 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.Developer/DeveloperMode
      directives:
        description: Enable Developer Mode
        allowPrerelease: true
      settings:
        Ensure: Present
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      id: vsPackage
      directives:
        description: Install Visual Studio 2022 Community
        allowPrerelease: true
      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
      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 库中的“预发布”模块。
设置：资源的 settings 值表示传递给 PowerShell DSC 资源的名称-值对的集合。设置可以表示从是否启用开发人员模式到应用注册表项或建立特定网络设置的任何内容。
依赖项：资源的 dependsOn 值决定在开始此任务之前是否必须完成任何其他断言或资源。如果依赖项失败，此资源也将自动失败。
ID：特定资源实例的唯一标识符。如果另一个资源依赖于首先应用的此资源，则可以使用 id 值。

组织“资源”部分

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

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

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

使用变量 ${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 配置文件的可信度。