PowerToys DSC App 模块：用 get / set / test 声明式管理全局设置

PowerToys 通过 DSC（Desired State Configuration）v3 支持声明式配置管理，其中的 App 模块专门负责全局级设置——包括每个实用工具的启用/禁用状态、开机自启动、管理员权限运行和应用主题。本文以 doc/dsc/modules/App.md 参考文档为主体，完整讲解 App 模块的全部配置属性与六类标准操作示例，并结合 SettingsResource.cs 与 GeneralSettings.cs 等源码，说明这些属性最终如何落到 PowerToys 设置文件上，读完后你可以直接用 PowerToys.DSC.exe、dsc config 或 winget configure 三种方式批量治理 PowerToys 环境。

一、App 模块的定位：管理"应用级"设置

App 模块管理的是影响整个 PowerToys 应用的全局设置：哪些实用工具被启用、PowerToys 是否在登录时自动启动、应用主题，以及其他通用偏好。与其他只配置单一工具（如 FancyZones、Awake）的模块不同，App 模块管理的是 PowerToys 全局偏好以及所有实用工具的启用状态。

从源码看，App 模块在 DSC 资源层有特殊地位。在 SettingsResource.cs 中：

• 常量 AppModule = "App" 定义了模块名；
• ModuleOrDefault 属性表明：当命令行未显式指定 --module 时，默认就路由到 App 模块（string.IsNullOrEmpty(Module) ? AppModule : Module）；
• App 模块绑定的配置类型是 GeneralSettings，即 CreateModuleFunctionData<GeneralSettings>()，这也是 PowerToys 设置界面"常规"页面对应的同一份配置模型。

因此，App 模块实际上就是 DSC 视角下的 GeneralSettings 读写通道。

二、属性参考

App 模块支持以下可配置属性。

2.1 Enabled（对象）

控制启用或禁用哪些 PowerToys 实用工具。类型为 Object，包含 25 个布尔属性：

• AdvancedPaste（boolean）——启用/禁用 Advanced Paste。
• AlwaysOnTop（boolean）——启用/禁用 Always On Top。
• Awake（boolean）——启用/禁用 Awake。
• ColorPicker（boolean）——启用/禁用 Color Picker。
• CropAndLock（boolean）——启用/禁用 Crop And Lock。
• EnvironmentVariables（boolean）——启用/禁用 Environment Variables。
• FancyZones（boolean）——启用/禁用 FancyZones。
• FileLocksmith（boolean）——启用/禁用 File Locksmith。
• FindMyMouse（boolean）——启用/禁用 Find My Mouse。
• Hosts（boolean）——启用/禁用 Hosts File Editor。
• ImageResizer（boolean）——启用/禁用 Image Resizer。
• KeyboardManager（boolean）——启用/禁用 Keyboard Manager。
• MeasureTool（boolean）——启用/禁用 Measure Tool。
• MouseHighlighter（boolean）——启用/禁用 Mouse Highlighter。
• MouseJump（boolean）——启用/禁用 Mouse Jump。
• MousePointerCrosshairs（boolean）——启用/禁用 Mouse Pointer Crosshairs。
• Peek（boolean）——启用/禁用 Peek。
• PowerAccent（boolean）——启用/禁用 Power Accent。
• PowerOCR（boolean）——启用/禁用 Power OCR。
• PowerRename（boolean）——启用/禁用 Power Rename。
• RegistryPreview（boolean）——启用/禁用 Registry Preview。
• ShortcutGuide（boolean）——启用/禁用 Shortcut Guide。
• Workspaces（boolean）——启用/禁用 Workspaces。
• ZoomIt（boolean）——启用/禁用 ZoomIt。

对应源码中，该属性映射到 GeneralSettings.cs 的 Enabled 属性（JSON 名 enabled，类型为 EnabledModules）。注意 Enabled 上带有 [CmdConfigureIgnore] 标记，从源码结构看，它不走 winget configure 的简化通道，而是由 DSC settings 资源（即本文的 App 模块）来管理。

2.2 startup（boolean）

控制 PowerToys 是否在登录时自动启动。文档标注默认值为 true。对应源码属性 Startup（JSON 名 startup，见 GeneralSettings.cs）。需要留意的是，GeneralSettings 类的构造函数将 Startup 初始化为 false（见 GeneralSettings.cs 的构造器），即新建配置对象的初始值为关闭；文档所述默认值 true 是安装后实际生效的默认行为，二者语义不同，编写期望状态时建议显式写出 startup: true/false，避免依赖隐式默认。

2.3 run_elevated（boolean）

控制 PowerToys 是否以管理员权限运行。文档标注默认值为 false。对应源码属性 RunElevated（JSON 名 run_elevated，见 GeneralSettings.cs）。该属性同样带有 [CmdConfigureIgnoreAttribute]，即通过 DSC 的 App 模块通道设置，而非 winget configure 通道。

2.4 theme（string）

设置应用主题。允许取值："light"、"dark"、"system"，默认 "system"。对应源码属性 Theme，构造函数中初始值即为 "system"（见 GeneralSettings.cs）。

三、实现纵深：DSC 如何读写 App 模块

理解以下机制后，你可以预期每种命令的确切行为：

1. get/export 同源：SettingsResource.cs 中 GetState 直接调用 ExportState，后者读取当前 GeneralSettings 并输出一行 JSON。因此 get 与 export 子命令对 App 模块完全等价。
2. set 是幂等的：SetState 会先 GetState() 读取现状、计算 diff，然后仅当 TestState() 判定期望状态与当前状态不一致时才真正写入（data.SetState()），最后依次输出"新状态 JSON"和"差异 JSON"两行（见 SettingsResource.cs）。重复执行相同的 set 不会产生副作用。
3. test 返回 _inDesiredState：TestState 输出当前状态 JSON、差异 JSON，并在状态对象中设置 InDesiredState 字段，供脚本判断（见 SettingsResource.cs），这正是下文示例 4 中 $result._inDesiredState 的来源。
4. manifest 自带预检：App 模块生成的 DSC 资源 manifest 对 set 方法声明了 implementsPretest: true 与 stateAndDiff: true（见 SettingsResource.cs），DSC 引擎可据此在执行 set 前自动预检、并消费输出的状态与 diff。
5. 单元测试覆盖：SettingsResourceAppModuleTest.cs 基于 SettingsResourceModuleTest<GeneralSettings> 对 App 模块做参数化测试，测试修改器翻转 Startup、ShowSysTrayIcon、Enabled.Awake、Enabled.ColorPicker 等属性，验证 get/set/test 链路对 App 模块的端到端一致性。
6. 不支持的模块边界：在 SettingsResource.cs 的注释中，MouseWithoutBorders（配置含敏感值）、PowerLauncher 与 NewPlus（配置含绝对路径、跨机不可移植）明确不在 DSC 支持列表内，这也解释了为何 App 模块的 Enabled 列表只有上述 25 项。

四、实战示例

以下六个示例完整继承自 App 模块参考文档，均可在已安装当前版本 PowerToys 的 Windows 环境中直接运行。

示例 1：直接执行方式，仅启用指定工具

只启用 FancyZones、PowerRename、ColorPicker，禁用其余工具。

$config = @{
    settings = @{
        properties = @{
            Enabled = @{
                AdvancedPaste = $false
                AlwaysOnTop = $false
                Awake = $false
                ColorPicker = $true
                CropAndLock = $false
                EnvironmentVariables = $false
                FancyZones = $true
                FileLocksmith = $false
                FindMyMouse = $false
                Hosts = $false
                ImageResizer = $false
                KeyboardManager = $false
                MeasureTool = $false
                MouseHighlighter = $false
                MouseJump = $false
                MousePointerCrosshairs = $false
                Peek = $false
                PowerAccent = $false
                PowerOCR = $false
                PowerRename = $true
                RegistryPreview = $false
                ShortcutGuide = $false
                Workspaces = $false
                ZoomIt = $false
            }
        }
        name = "App"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module App --input $config

示例 2：用 DSC 配置自启动与主题

配置 PowerToys 登录时自启动、以管理员权限运行，并使用深色主题。

dsc config set --file app-config.dsc.yaml

# app-config.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure PowerToys general settings
    type: Microsoft.PowerToys/AppSettings
    properties:
      settings:
        properties:
          startup: true
          run_elevated: true
          theme: dark
        name: App
        version: 1.0

示例 3：用 WinGet 一键安装并启用全部工具

安装 PowerToys 并启用所有可用工具。

winget configure winget-enable-all.yaml

# winget-enable-all.yaml
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
  winget:
    processor: dscv3
resources:
  - name: Install PowerToys
    type: Microsoft.WinGet.DSC/WinGetPackage
    properties:
      id: Microsoft.PowerToys
      source: winget

  - name: Enable all utilities
    type: Microsoft.PowerToys/AppSettings
    properties:
      settings:
        properties:
          Enabled:
            AdvancedPaste: true
            AlwaysOnTop: true
            Awake: true
            ColorPicker: true
            CropAndLock: true
            EnvironmentVariables: true
            FancyZones: true
            FileLocksmith: true
            FindMyMouse: true
            Hosts: true
            ImageResizer: true
            KeyboardManager: true
            MeasureTool: true
            MouseHighlighter: true
            MouseJump: true
            MousePointerCrosshairs: true
            Peek: true
            PowerAccent: true
            PowerOCR: true
            PowerRename: true
            RegistryPreview: true
            ShortcutGuide: true
            Workspaces: true
            ZoomIt: true
        name: App
        version: 1.0

仓库中还附带了 enableAllModules.winget 这类现成示例，可对照了解 Microsoft.PowerToys.Configure DSC 模块的完整启用清单写法（其覆盖的工具范围比 DSC settings 资源更宽，包含 MouseWithoutBorders、NewPlus 等）。

示例 4：检测指定工具是否已启用

测试 FancyZones 与 PowerRename 是否处于启用状态。

$desired = @{
    settings = @{
        properties = @{
            Enabled = @{
                FancyZones = $true
                PowerRename = $true
            }
        }
        name = "App"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

$result = PowerToys.DSC.exe test --resource 'settings' --module App `
    --input $desired | ConvertFrom-Json

if ($result._inDesiredState) {
    Write-Host "FancyZones and PowerRename are enabled"
} else {
    Write-Host "Configuration needs to be updated"
}

如第三节所述，test 命令同时输出状态 JSON 与差异 JSON 两行，解析时取第一行即可；_inDesiredState 为 true 时说明期望项全部满足。

示例 5：逐工具精细配置

先读取现状，再单独启用某个工具，获得更细粒度的控制。

# Get current state
PowerToys.DSC.exe get --resource 'settings' --module App

# Enable individual utilities
$config = @{
    settings = @{
        properties = @{
            Enabled = @{
                FancyZones = $true
            }
        }
        name = "App"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module App --input $config

由于 set 只写与期望不同的字段（幂等），单独启用 FancyZones 不会影响其他工具的现有状态。

示例 6：获取 App 模块的 JSON Schema

拉取完整 schema，便于在编辑器中获得配置自动补全或做静态校验。

PowerToys.DSC.exe schema --resource 'settings' --module App | `
    ConvertFrom-Json | ConvertTo-Json -Depth 10

五、延伸阅读

• Settings Resource：settings 资源本身的方法与协议细节。
• PowerToys DSC Overview：三种使用方式（直接执行、DSC 配置文档、WinGet 配置）与全部支持模块清单。
• Awake 模块：作为单工具模块与 App 模块写法对比的参考。
• SettingsResource.cs 与 SettingsResourceAppModuleTest.cs：App 模块的实现与测试代码。

适用前提：以上命令要求当前版本 PowerToys 已在系统上安装，PowerToys.DSC.exe 随安装包提供；DSC v3 / winget configure 方式还需系统具备对应版本的 DSC 引擎。属性清单与默认值以 App 模块文档 和当前仓库 GeneralSettings.cs 的实际实现为准。