编写 WinGet 配置文件复现开发环境-未完纪

WinGet 配置文件描述开发环境所需的先决条件、软件与系统设置。创建文件时，可以按下面的顺序组织工作：

按命名约定新建 YAML 文件。
了解文件格式，并链接相应的 JSON 架构。
列出断言与资源：断言描述先决条件，资源描述应安装的工具以及应达到的设置状态。
确定执行这些任务需要哪些 PowerShell 模块与 Desired State Configuration（DSC，期望状态配置）资源。
为每个资源填写指令与设置。
明确资源之间的依赖关系。

文件格式

Windows 包管理器使用 YAML 清单查找和安装软件包。WinGet 配置文件同样使用 YAML，并借助 JSON 架构定义结构、校验格式。可在 Visual Studio Code 中安装 Red Hat 的 YAML 扩展；关联架构后，编辑器可提供语法检查、悬停提示和自动补全。

文件命名约定

文件扩展名采用 .winget，例如 configuration.winget。对于 Git 项目，将默认配置放在 ./.config/configuration.winget。如果不同工具链或用户偏好需要多份配置，其他文件也应放在 .config 目录中。

配置文件的两个主要部分

assertions：运行配置所需的先决条件。
resources：要安装的软件与工具，以及应用程序和 Windows 操作系统的设置。

断言

断言用于检查资源能否在当前计算机上成功执行。断言可以并行完成，无须按顺序排列。例如，可以检查最低操作系统版本。系统功能可能随版本增加，其中有些会回移到旧版本，有些不会，因此应按所需工具或功能核对最低版本。WinGet 至少需要 Windows 10 1809 或更新版本。

DSC 资源能够改变系统状态，但在开源项目的环境配置中调用 Windows Update 来修改操作系统版本并不合适。如果断言返回 false，通过 dependsOn 依赖该断言的资源会被跳过。原文说明，这种情形下，即使没有应用环境变更，配置仍可能被视为成功；应结合各资源结果判断实际环境状态。

资源

资源列表包含需要安装的软件、工具、软件包，以及操作系统或已安装应用的设置。每项任务都需标明资源名称、要执行的任务说明、负责执行的 PowerShell 模块、相关设置与依赖。

完整配置示例

下面保留原文的 configuration.winget 示例。它使用 0.2 架构，检查系统版本、启用开发者模式、安装 Visual Studio 2022 Community，然后按项目的 .vsconfig 安装工作负载。

# 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 语言服务器采用哪个 DSC 架构。示例指定 https://aka.ms/configuration-dsc-schema/0.2。可从架构入口确认当前适用版本；0.2 是这个示例的版本，不表示永远最新。
属性。该格式以 properties 为根节点，包含 configurationVersion（示例为 0.2.0）、assertions 和 resources。配置版本应与采用的配置格式保持一致。
断言。在 assertions 中列出先决条件。
资源。断言与资源列表均以单独的 resource 节点描述任务，命名格式为 {ModuleName}/{DscResource}。每项包括 directives、settings，并可指定 id。应用配置时，WinGet 从 PowerShell Gallery 获取模块并调用指定 DSC 资源。
指令。directives 提供模块与资源的信息。description 描述任务；allowPrerelease: true 允许采用预发布模块。需要管理员权限的资源可设置 securityContext: elevated。WinGet 会在配置开始时请求一次 UAC 批准，再分别以提升权限和当前用户权限运行相应资源。
设置。settings 是传递给 DSC 资源的名称与值，可用于开发者模式、注册表或网络等设置。
依赖。dependsOn 指定此任务开始前必须完成的断言或资源。原文区分了断言不满足时的跳过与依赖失败引起的资源失败。
标识。id 唯一标识一个资源实例，让其他资源引用它。示例中的 VS 工作负载依赖 vsPackage，因此先安装 Visual Studio，再安装工作负载。

示例边界：系统版本断言没有设置 id，其他资源也没有通过 dependsOn 引用该断言；不要把这个示例理解为所有资源都受该断言依赖保护。列表位置用于阅读，执行前置关系应由依赖字段明确表达。

组织资源列表

可以按三种思路组织资源，帮助维护者理解文件：

逻辑执行顺序：按安装、安装后设置等步骤排列，便于阅读自动化过程。
失败可能性：突出容易失败的步骤，便于尽早识别问题及其对后续任务的影响。
类似资源分组：把相同类型的资源放在一起，采用开发者熟悉的组织方式。

公开发布开源配置时，建议同时提供 README.md，说明所采用的文件组织方式。实际执行顺序仍需要正确的依赖关系。

使用变量 `${WinGetConfigRoot}`

某些 DSC 资源接受文件路径参数。使用 ${WinGetConfigRoot} 并追加相对路径，可以避免把具体计算机的绝对路径写入配置。原文将其描述为执行 winget configure 时的工作目录；使用前应核对目标文件相对位置。上面的 VSComponents 示例用它引用项目根目录中的 .vsconfig。执行前确认文件存在，且路径与配置所在位置相符。

查找 PowerShell DSC 资源模块

Microsoft 支持的现成 DSC 资源包括：

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

资源入口见 PSDscResources 概览。也可在 PowerShell Gallery 按“DSC Resources”分类筛选社区模块。Gallery 中的模块来自不同作者和发布者，并非全部经 Microsoft 验证。使用前审查模块来源与脚本内容，因为资源可能运行任意脚本。进一步参见检查配置文件的可信度。