PowerToys DSC settings 资源配置完全指南用声明式配置管理全部模块【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys本文以 PowerToys 仓库中的 settings 资源参考文档 为主体结合src/dsc下PowerToys.DSC的 CLI 实现、单元测试与官方示例配置系统讲解如何通过 Microsoft Desired State ConfigurationDSCv3 以声明式方式查看、测试、导出与强制应用 PowerToys 各工具的配置状态。读完本文你将掌握PowerToys.DSC.exe的七个核心命令能够在普通 DSC 配置文档与 WinGet 配置工作流中开箱即用地管理 App、Awake、FancyZones、ColorPicker、ImageResizer 等模块的配置并理解settings资源背后的get / set / test / export / schema / manifest六种 DSC 协议操作的实现机制。1. 什么是 PowerToys DSC settings 资源settings资源是 PowerToys 为 Microsoft Desired State ConfigurationDSCv3 提供的配置管理资源由随 PowerToys 安装的PowerToys.DSC.exe命令行工具承载见仓库中的 PowerToys.DSC 工程。它的核心价值在于把“PowerToys 的配置”从图形设置界面中解放出来变成可声明、可测试、可强制执行的代码化状态为每一个 PowerToys 工具模块声明并强制执行期望的配置状态在多台机器之间自动化地同步 PowerToys 配置与 WinGet 以及其他支持 DSC v3 的工具链集成将 PowerToys 设置纳入版本控制即 Settings as Code。每个 PowerToys 工具都有自己可管理的配置属性而settings资源在底层通过统一的资源抽象支持 DSC 的全部标准操作get、set、test、export以及面向 DSC 宿主协议的schema与manifest生成。从源码看这一抽象由三部分组成程序入口 Program.cs 基于System.CommandLine注册了七个根命令get、set、export、test、schema、manifest与modules资源抽象基类 BaseResource.cs 定义了GetState/SetState/TestState/ExportState/Schema/Manifest/GetSupportedModules七个抽象方法并统一负责 JSON 输出成功信息写入 stdout错误、警告等信息以 JSON 形式写入 stderr具体实现 SettingsResource.cs 维护了一张“模块名 → 设置类型”的字典将 25 个模块映射到Microsoft.PowerToys.Settings.UI.Library中的对应强类型设置类。2. settings 资源支持的模块清单settings资源几乎覆盖了 PowerToys 的全部工具模块模块用途详细属性文档App全局应用设置工具开关、开机启动、主题等App 模块AdvancedPaste高级剪贴板与粘贴操作AdvancedPaste 模块AlwaysOnTop窗口置顶配置AlwaysOnTop 模块Awake保持唤醒定时器设置Awake 模块ColorPicker取色器激活与格式设置ColorPicker 模块CropAndLock窗口裁剪设置CropAndLock 模块EnvironmentVariables环境变量编辑器设置EnvironmentVariables 模块FancyZones窗口布局与分区配置FancyZones 模块FileLocksmith文件占用检测设置FileLocksmith 模块FindMyMouse鼠标定位器设置FindMyMouse 模块HostsHosts 文件编辑器设置Hosts 模块ImageResizer图片尺寸调整配置ImageResizer 模块KeyboardManager按键重映射与快捷键设置KeyboardManager 模块MeasureTool屏幕测量工具设置MeasureTool 模块MouseHighlighter鼠标高亮配置MouseHighlighter 模块MouseJump鼠标跳转导航设置MouseJump 模块MousePointerCrosshairs鼠标十字准星显示设置MousePointerCrosshairs 模块Peek文件预览设置Peek 模块PowerAccent快速输入重音字符设置PowerAccent 模块PowerOCR屏幕文字提取设置PowerOCR 模块PowerRename批量重命名配置PowerRename 模块RegistryPreview注册表文件预览设置RegistryPreview 模块ShortcutGuide快捷键覆盖层显示设置ShortcutGuide 模块Workspaces应用工作区设置Workspaces 模块ZoomIt屏幕缩放与标注设置ZoomIt 模块说明与仓库 overview 文档 中列出的模块相比源码中的映射表见 SettingsResource.cs并未包含 MouseWithoutBorders、PowerLauncherCommand Palette与 NewPlus。源码注释给出的原因是MouseWithoutBorders 包含敏感配置值导出/导入存在安全隐患而 PowerLauncher 与 NewPlus 的设置中使用了绝对文件路径跨机器不可移植。若要配置上述三个模块需要直接使用其配置文件或图形界面无法通过settings资源导出迁移。每个模块可配置的具体属性类型、取值范围、默认值、示例在 doc/dsc/modules 目录下均有独立参考文档。3. 支持的三种使用方式PowerToys DSC 提供三种等效的使用方式你可以根据自己的工作流选择。3.1 直接执行PowerToys.DSC.exe最轻量的方式直接在命令行PowerShell中执行工具命令# 获取某个模块的当前配置 PowerToys.DSC.exe get --resource settings --module Awake # 设置某个模块的期望配置 $input {settings:{...}} PowerToys.DSC.exe set --resource settings --module Awake --input $input # 测试当前配置是否与期望一致 PowerToys.DSC.exe test --resource settings --module Awake --input $input命令统一遵守command --resource settings --module ModuleName的参数约定--input用于传入 JSON 格式的期望状态。3.2 标准 DSC 配置文档dsc 命令 / dscv3把资源配置写入符合 DSC v3 schema 的 YAML 文档交由 DSC 宿主执行# powertoys-config.dsc.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Configure Awake type: Microsoft.PowerToys/AwakeSettings properties: settings: properties: keepDisplayOn: true mode: 1 name: Awake version: 0.0.1资源type的命名遵循Microsoft.PowerToys/ModuleSettings模式。settings对象内部包含name模块名、version配置 schema 版本号与properties各模块实际配置项三个部分这一结构与直接执行时--input传入的 JSON 完全同构。3.3 WinGet 配置将 PowerToys 的安装与配置编排进同一条 WinGet Configuration 文档实现“安装即配置”# winget-powertoys.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: Configure FancyZones type: Microsoft.PowerToys/FancyZonesSettings properties: settings: properties: fancyzones_shiftDrag: true fancyzones_mouseSwitch: true name: FancyZones version: 1.0该文档使用Microsoft.WinGet.DSC/WinGetPackage先安装Microsoft.PowerToys再通过Microsoft.PowerToys/FancyZonesSettings资源应用配置。实践提示仓库中提供了大量可直接改用的官方示例见 src/dsc/Microsoft.PowerToys.Configure/examples包括enableAllModules.winget启用全部模块、disableAllModules.winget禁用全部模块、installAndConfiguration.winget安装并配置与configuration.winget纯配置等场景。4. settings 资源的全部操作详解4.1 列出支持的模块modules查看当前settings资源可以配置哪些模块# 列出全部可配置模块。 PowerToys.DSC.exe modules --resource settings底层对应 SettingsResource.GetSupportedModules()返回按字母序排序的模块字典键集合。4.2 获取当前状态get / export读取模块的当前配置状态。export与get输出完全一致——从源码看GetState直接委托给ExportStateSettingsResource.cs因此两者的 JSON 输出格式完全相同。直接执行# 获取某模块的当前设置。 PowerToys.DSC.exe get --resource settings --module ModuleNameDSC 配置以获取 Awake 当前状态为例只需给出空properties即可触发 get 语义$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Get Awake settings type: Microsoft.PowerToys/AwakeSettings properties: {}WinGet 配置同理例如查询 FancyZones 的当前状态$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json metadata: winget: processor: dscv3 resources: - name: Get FancyZones settings type: Microsoft.PowerToys/FancyZonesSettings properties: {}4.3 导出当前状态exportexport与get语义一致用于备份或采集当前配置# 导出某模块当前设置。 PowerToys.DSC.exe export --resource settings --module ModuleName一个常见的自动化用法是遍历modules输出把每个模块的配置导出汇总成一份 JSON 备份文件详见第 6 节的示例五。4.4 设置期望状态set向模块下发期望配置只更新与期望状态存在差异的属性。从源码看SetState会先GetState()拉取当前值、计算差异 JSON再通过TestState()判断是否已一致只有在不一致时才真正写回设置SettingsResource.cs。直接执行以 Awake 模块为例期望“保持屏幕常亮且无限期唤醒”# 为模块设置期望配置。 $input { settings: { properties: { keepDisplayOn: true, mode: 1 }, name: Awake, version: 0.0.1 } } PowerToys.DSC.exe set --resource settings --module Awake --input $inputDSC 配置$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Configure Awake type: Microsoft.PowerToys/AwakeSettings properties: settings: properties: keepDisplayOn: true mode: 1 name: Awake version: 0.0.1WinGet 配置将“安装 PowerToys 配置 FancyZones”放在同一文档中$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json metadata: winget: processor: dscv3 resources: - name: Install and configure PowerToys type: Microsoft.WinGet.DSC/WinGetPackage properties: id: Microsoft.PowerToys source: winget - name: Configure FancyZones type: Microsoft.PowerToys/FancyZonesSettings properties: settings: properties: fancyzones_shiftDrag: true fancyzones_mouseSwitch: true fancyzones_displayOrWorkAreaChange_moveWindows: true name: FancyZones version: 1.04.5 测试期望状态test校验当前配置是否与期望状态一致即检测“配置漂移”。返回的输出中包含_inDesiredState属性值为true表示一致false表示有差异。直接执行# 测试当前状态是否与期望一致。 $input { settings: { properties: { keepDisplayOn: true, mode: 1 }, name: Awake, version: 0.0.1 } } PowerToys.DSC.exe test --resource settings --module Awake --input $inputDSC 配置$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Test Awake configuration type: Microsoft.PowerToys/AwakeSettings properties: settings: properties: keepDisplayOn: true mode: 1 name: Awake version: 0.0.1从源码可以看到test与set共享同一套状态比较与差异计算逻辑TestState会调用data.GetState()、把比较结果写入输出的InDesiredState并同时输出差异 JSONSettingsResource.cs。差异输出由SettingsFunctionData.GetDiffJson()生成供上层判断具体哪些属性需要修正。4.6 生成 JSON Schemaschema为某个模块生成 JSON Schema描述该模块全部可配置属性及其类型、取值范围可用于编辑器补全、校验或生成图形表单。直接执行# 获取某模块的 JSON Schema。 PowerToys.DSC.exe schema --resource settings --module Awake # 通过管道格式化便于阅读。 PowerToys.DSC.exe schema --resource settings --module Awake | ConvertFrom-Json | ConvertTo-Json -Depth 10纵深背景仓库中的 PowerToys.Settings.DSC.Schema.Generator 工程Program.cs、SchemaGeneration.cs、DSCGeneration.cs等以静态工具的形式生成模块属性 JSON Schema、DSC 配置示例乃至每模块的 Markdown 文档——doc/dsc/modules/下各模块文档即由该生成器产出保证了“模块属性文档、schema、运行时校验”三者的同源一致。4.7 生成 DSC 资源 Manifestmanifest生成符合 DSC v3 协议规范的资源 Manifest 文件供 DSC 宿主dscv3 / WinGet发现资源能力stdin/json-input/command 方法、是否支持 pretest 等。可以针对单模块生成也可以一次生成全部模块的 Manifest。直接执行# 为指定模块生成 Manifest 到目录。 $outputDir C:\manifests PowerToys.DSC.exe manifest --resource settings --module Awake --outputDir $outputDir # 为所有模块生成 Manifest。 PowerToys.DSC.exe manifest --resource settings --outputDir $outputDir # 不指定 --outputDir 时把 Manifest 直接打印到控制台。 PowerToys.DSC.exe manifest --resource settings --module Awake底层实现中Manifest会生成名为microsoft.powertoys.module.settings.dsc.resource.json的资源描述文件SettingsResource.cs每个 Manifest 会声明该模块的export/get为 stdin 方法、set/test为 json-input 方法其中set开启implementsPretest与stateAndDiff、schema为 command 方法见GenerateManifest实现 SettingsResource.cs。5. 各模块的核心配置属性速览settings资源的properties即对应各模块配置文件JSON中的实际字段。以下以最常用的三个模块为例说明属性形态完整清单见各模块参考文档5.1 App 模块全局设置App 模块管理的是 PowerToys 全局状态与其他模块的开头状态注意它的属性是全局粒度的不依赖src/modules下某个具体工具工程EnabledObject每个工具的布尔开关如Awake、FancyZones、PowerRename、ColorPicker、AdvancedPaste等对应 App.md 中列出的 24 个工具键startupboolean默认true登录时是否自动启动 PowerToysrun_elevatedboolean默认false是否以管理员权限运行themestring取值light/dark/system默认system应用主题。5.2 Awake 模块保持唤醒Awake 模块属性在 Awake.md 中有完整参考keepDisplayOnboolean默认true为true时防止显示器关闭为false时仅阻止系统睡眠、显示器仍遵循电源计划关闭modeinteger默认00关闭、1无限期保持唤醒、2定时唤醒配合intervalHours/intervalMinutes、3保持唤醒到指定时刻配合expirationDateTimeintervalHoursinteger0–999与 intervalMinutesinteger0–59mode2时的定时时长expirationDateTimeISO 8601 字符串mode3的到期时间格式形如2025-12-31T23:59:59.0000000-08:00customTrayTimesobject托盘右键菜单中的自定义快捷时长预设键为显示名、值为时长定义。5.3 FancyZones 模块窗口布局FancyZones 模块FancyZones.md的属性与设置界面中的功能开关一一对应例如fancyzones_shiftDragboolean默认true拖动窗口时按住 Shift 是否触发分区吸附fancyzones_mouseSwitchboolean默认false拖动窗口跨显示器时是否弹出分区选择fancyzones_overrideSnapHotkeysboolean默认false是否覆盖 Windows 系统贴靠热键Win方向键fancyzones_displayOrWorkAreaChange_moveWindowsboolean显示器分辨率或工作区变化时是否移动窗口适配fancyzones_zoneSetChange_moveWindowsboolean切换布局方案时是否自动移动窗口fancyzones_appLastZone_moveWindowsboolean默认true应用再次打开时是否恢复到上次所在分区fancyzones_overlappingZonesAlgorithminteger多分区重叠时的命中算法0最小分区、1最大分区、2按位置。这些属性名与src/modules/fancyzones中实际持久化的设置键一致属性改动会直接落到本机 PowerToys 的配置存储中重启对应模块后生效。6. 综合示例示例 1启用并配置 FancyZones直接执行先用get拉取当前配置再构造期望状态并以set应用# 获取当前 FancyZones 配置。 $current PowerToys.DSC.exe get --resource settings --module FancyZones | ConvertFrom-Json # 构造期望状态。 $desired { settings { properties { fancyzones_shiftDrag $true fancyzones_mouseSwitch $true fancyzones_displayOrWorkAreaChange_moveWindows $true } name FancyZones version 1.0 } } | ConvertTo-Json -Depth 10 -Compress # 应用配置。 PowerToys.DSC.exe set --resource settings --module FancyZones --input $desired这种“先 get 当前值 → 构造 HashTable → 压缩成 JSON → set 应用”的模式适合在脚本中做增量修改避免手工拼写完整 JSON。示例 2一份配置文档同时管理多个工具在单个 DSC 文档里声明 App工具开关、Awake 与 ColorPicker 的期望状态# powertoys-multi.dsc.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Enable PowerToys utilities type: Microsoft.PowerToys/AppSettings properties: settings: properties: Enabled: Awake: true FancyZones: true PowerRename: true ColorPicker: true name: App version: 1.0 - name: Configure Awake type: Microsoft.PowerToys/AwakeSettings properties: settings: properties: keepDisplayOn: true mode: 1 name: Awake version: 0.0.1 - name: Configure ColorPicker type: Microsoft.PowerToys/ColorPickerSettings properties: settings: properties: changecursor: true copiedcolorrepresentation: HEX name: ColorPicker version: 1.0注意同一文档中每个资源type都使用各自的ModuleSettings资源名但它们在实现上都由同一个PowerToys.DSC.exesettings 资源在背后驱动即 manifest 生成时每个模块独立一个 manifest、但指向同一个--resource settings调用见 4.7 节。示例 3WinGet 安装 PowerToys 并应用通用/布局/图像配置把包安装与三层配置编排在一条文档中然后交给winget configure执行# winget-powertoys-setup.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 ensure: Present - name: Configure general settings type: Microsoft.PowerToys/AppSettings properties: settings: properties: run_elevated: true startup: true theme: dark name: App version: 1.0 - name: Configure FancyZones type: Microsoft.PowerToys/FancyZonesSettings properties: settings: properties: fancyzones_shiftDrag: true fancyzones_zoneSetChange_moveWindows: true name: FancyZones version: 1.0 - name: Configure ImageResizer type: Microsoft.PowerToys/ImageResizerSettings properties: settings: properties: ImageResizerSizes: - Name: Small Width: 854 Height: 480 Unit: Pixel Fit: Fit - Name: Medium Width: 1920 Height: 1080 Unit: Pixel Fit: Fit name: ImageResizer version: 1.0应用这条配置winget configure winget-powertoys-setup.yaml其中ImageResizerSizes展示了数组嵌套对象属性的写法每个尺寸包含 Name / Width / Height / Unit / Fit这类结构化属性在 ImageResizer 等模块中很常见。示例 4检测并修复配置漂移用test判定是否漂移若已漂移则直接以set修复——这是 DSC“声明式收敛”在 PowerShell 脚本中的最小落地实现# 定义期望状态。 $desired { settings { properties { keepDisplayOn $true mode 1 } name Awake version 0.0.1 } } | ConvertTo-Json -Depth 10 -Compress # 测试是否有漂移。 $result PowerToys.DSC.exe test --resource settings --module Awake --input $desired | ConvertFrom-Json if ($result._inDesiredState) { Write-Host Configuration is in desired state } else { Write-Host Configuration has drifted from desired state # 修复漂移应用配置。 PowerToys.DSC.exe set --resource settings --module Awake --input $desired }示例 5导出全部模块配置做备份遍历modules输出逐个export最后落盘为一份 JSON 备份# 获取全部模块列表。 $modules PowerToys.DSC.exe modules --resource settings # 逐个导出模块配置。 $configurations {} foreach ($module in $modules) { $config PowerToys.DSC.exe export --resource settings --module $module | ConvertFrom-Json $configurations[$module] $config } # 保存到文件。 $configurations | ConvertTo-Json -Depth 10 | Out-File powertoys-backup.json由于export与get输出完全一致见 4.2 节源码说明该脚本也可用get替代export。注意第 2 节提到的不支持模块MouseWithoutBorders、PowerLauncher、NewPlus不会出现在列表中如需备份需另行处理其设置文件。7. 从源码理解 settings 资源的内部工作机制7.1 模块分发的核心模块名 → 强类型设置类SettingsResource构造时用“模块名 → 工厂方法”的字典完成分发SettingsResource.cs{ AppModule, CreateModuleFunctionDataGeneralSettings }, // App { nameof(ModuleType.Awake), CreateModuleFunctionDataAwakeSettings }, // Awake { nameof(ModuleType.FancyZones), CreateModuleFunctionDataFancyZonesSettings },// FancyZones // ...每个工厂方法都要求设置类实现ISettingsConfig接口再包装成泛型 SettingsFunctionDataTSettingsConfig。这也解释了为什么“资源支持哪些模块”可以由modules命令枚举——本质就是遍历字典键。7.2 每条命令如何驱动资源操作Program.cs注册的七个命令类都继承 BaseCommand并把ExitCode与资源方法的返回值绑定方法返回true则退出码为0否则为1。例如 SetCommand.cs 内部执行Resource.SetState(Input)。命令选项--resource、--module、--input、--outputDir由 Options 目录下对应的选项类定义其中--resource默认为settings--module缺省时回退到App模块见 SettingsResource.cs 的ModuleOrDefault。7.3 测试如何保证正确性仓库为 settings 资源准备了完整的单元测试工程 PowerToys.DSC.UnitTests每个模块一个测试文件如 SettingsResourceAwakeModuleTest.cs、SettingsResourceFancyZonesModuleTest.cs并抽象出泛型基类 SettingsResourceModuleTest1.cs统一验证“get / set / test / schema”在各模块上的往返一致性。这一测试布局印证了 settings 资源的模块扩展方式是“表驱动”的新增模块主要是把新设置类型加入字典。7.4 与配置文件体系的关系从架构上看settings资源操作的属性与设置界面Settings.UI.Library中定义、各模块运行时读取的是同一份强类型设置结构。换句话说DSC 资源是“设置读写能力的命令行投影”把原来只能在图形界面或 JSON 文件中手工维护的配置变成可脚本化、可版本化、可被 DSC 引擎强制收敛的状态对象。8. 查看更多PowerToys DSC 概览三种使用方式与模块总览doc/dsc/modules各模块属性完整参考App、Awake、FancyZones、ColorPicker、ImageResizer 等 25 份文档src/dsc/v3/PowerToys.DSCsettings 资源与全部命令的源码实现src/dsc/v3/PowerToys.DSC.UnitTestssettings 资源的模块级单元测试src/dsc/Microsoft.PowerToys.Configure/examples可复制的 WinGet/DSC 示例配置src/dsc/PowerToys.Settings.DSC.Schema.GeneratorSchema、示例与模块文档的生成工具。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考