尧图网站建设 
PowerToys DSC 配置指南用 Desired State Configuration 将 PowerToys 各工具设置声明式地纳入代码管理与批量自动化【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToysPowerToys 官方基于 Microsoft Desired State ConfigurationDSCv3 提供了PowerToys DSC支持通过PowerToys.DSC.exe命令行工具与settings资源配置资源把 Awake、FancyZones、ImageResizer 等所有工具的设置变成可声明、可测试、可回滚的配置即代码。本文以 PowerToys DSC Overview 为骨架结合仓库源码完整讲解三种使用方式PowerToys.DSC.exe直接执行、标准 DSC v3 配置文档、WinGet Configuration、全部 CLI 操作、支持的模块与资源清单并给出可直接复制的端到端示例帮助你在多机环境统一管控 PowerToys 配置。DSC 是什么PowerToys 的声明式配置管理入口PowerToys DSCDesired State Configuration期望状态配置允许你描述PowerToys 应当处于什么配置状态而不是手动逐个点击设置界面。核心能力包括声明并强制执行PowerToys 各实用工具模块的期望配置状态跨多台系统自动化同步 PowerToys 配置告别逐台手工调整与 WinGet 及其他 DSC 兼容工具集成在安装包的同时落地配置将 PowerToys 设置作为代码纳入版本控制实现可审计、可复现的环境基线。PowerToys 的 DSC 实现对外暴露一个名为settings的资源resource统一管理所有 PowerToys 工具模块的配置每个工具可独立配置从而实现对整个 PowerToys 环境的细粒度控制。从源码角度印证settings资源在 SettingsResource.cs 中定义内部通过Dictionarystring, Funcstring?, ISettingsFunctionData把每个模块名映射到各自的设置类型如AwakeSettings、FancyZonesSettings并默认回落到App模块见ModuleOrDefault属性。而命令行入口 Program.cs 使用System.CommandLine注册了 7 个子命令get、set、export、test、schema、manifest、modules。三种使用方式PowerToys DSC 可以在三个层面被使用从单条命令手动操作到完整 YAML 配置文档托管按需选择即可。方式一使用 PowerToys.DSC.exe 直接执行在已安装 PowerToys 的环境里直接调用PowerToys.DSC.exe完成查询、设置与校验。基本语法为PowerToys.DSC.exe 命令 --resource settings --module 模块名 [--input JSON]。# 读取某个模块的当前配置 PowerToys.DSC.exe get --resource settings --module Awake # 向某个模块写入配置--input 传入 JSON 字符串 $input {settings:{...}} PowerToys.DSC.exe set --resource settings --module Awake --input $input # 校验当前配置是否等于期望配置test PowerToys.DSC.exe test --resource settings --module Awake --input $input从 BaseCommand.cs 可知所有子命令共享--module、--resource、--input三个选项并且命令执行前会先校验--module是否属于该资源支持的模块列表不支持的模块会直接报错并以退出码 1 结束。各子命令的完整用法见下文常用操作章节。方式二Microsoft DSC v3 标准配置文档把配置写成标准的 DSC v3 YAML 文档然后用dsc命令行应用。PowerToys 的资源类型按模块名Settings命名如Microsoft.PowerToys/AwakeSettings并被注册到 DSC v3 中# 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需要说明YAML 里type名称与模块文档一一对应且settings属性块内的name通常与模块名一致、version为该模块设置结构的版本号。资源类型实际由manifest命令生成命名格式见下文PowerToys 安装包中会携带这些资源清单以支持 DSC v3 协议调用。方式三WinGet Configuration 一体化把安装 PowerToys和配置工具写进同一个 WinGet 配置文档实现装机即到位# 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应用该文档时使用winget configure winget-powertoys.yaml或dsc config set --file ...。仓库中还提供了同类 winget 示例文件可供对照例如 installAndConfiguration.winget它演示了通过Microsoft.WinGet.DSC/WinGetPackage安装、再通过资源配置FancyZones、ImageResizer等模块的写法。可用资源ResourcePowerToys DSC 目前对外提供以下资源资源说明settings管理 PowerToys 各工具模块的配置settings资源内部把每个工具视为独立模块分别管理。在 SettingsResource.cs 中可以确认资源名常量ResourceName settings。该资源支持标准 DSC 操作get、set、test、export、schema与manifest生成。详细参考见 Settings Resource Reference。可用模块Modules总览settings资源支持配置以下 PowerToys 工具。下表同时给出各模块的详细属性文档位于doc/dsc/modules/目录可点击深入了解每个模块的可配置属性、类型、默认值与示例。模块说明详细文档AppPowerToys 应用级通用设置工具启停、开机启动、主题等App 模块AdvancedPaste高级剪贴板/粘贴操作AdvancedPaste 模块AlwaysOnTop窗口置顶AlwaysOnTop 模块Awake保持电脑唤醒Awake 模块ColorPicker全局取色器ColorPicker 模块CropAndLock裁剪并锁定窗口区域CropAndLock 模块EnvironmentVariables管理环境变量EnvironmentVariables 模块FancyZones窗口布局管理FancyZones 模块FileLocksmith定位占用文件的进程FileLocksmith 模块FindMyMouse定位鼠标光标FindMyMouse 模块Hosts快速编辑 hosts 文件Hosts 模块ImageResizer右键菜单批量改图尺寸ImageResizer 模块KeyboardManager按键重映射与快捷键KeyboardManager 模块MeasureTool屏幕像素测量MeasureTool 模块MouseHighlighter高亮鼠标光标MouseHighlighter 模块MouseJump大屏/多屏间快速跳转鼠标MouseJump 模块MousePointerCrosshairs鼠标居中十字准星MousePointerCrosshairs 模块Peek快速文件预览Peek 模块PowerAccent快速插入带音调字符PowerAccent 模块PowerOCR从图片提取文字PowerOCR 模块PowerRename批量重命名PowerRename 模块RegistryPreview可视化编辑注册表文件RegistryPreview 模块ShortcutGuide显示 Windows 快捷键指南ShortcutGuide 模块Workspaces应用窗口集的保存与恢复Workspaces 模块ZoomIt屏幕缩放与标注ZoomIt 模块值得注意的是settings资源并不支持所有PowerToys 模块。查看 SettingsResource.cs 中的源码注释可以发现当前明确被排除的模块包括MouseWithoutBorders配置中含敏感信息导入/导出可能存在安全隐患PowerLauncher设置中保存了绝对文件路径跨机器不可移植NewPlus同样使用绝对文件路径不可移植。如果你计划用 PowerToys DSC 做大规模部署应提前确认目标配置确实落在这 25 个受支持模块范围内。常用操作PowerToys.DSC.exe 命令详解以下命令均可在 PowerShell 中直接执行PowerToys.DSC.exe随 PowerToys 安装建议在安装目录或将其加入 PATH 后调用。这些操作与 settings-resource.md 中描述的 DSC 行为一一对应底层均由各*Command.cs转发给SettingsResource处理。列出全部受支持模块PowerToys.DSC.exe modules --resource settings该命令对应源码 ModulesCommand.cs它调用GetSupportedModules()返回按名称排序的模块列表——即上表列出的 25 个模块。读取当前配置get / export# 读取指定模块的当前配置 PowerToys.DSC.exe get --resource settings --module FancyZones # 导出配置与 get 输出完全一致 PowerToys.DSC.exe export --resource settings --module FancyZones从源码看get与export行为等价——SettingsResource.cs 中GetState()直接复用了ExportState()的逻辑先创建该模块的 FunctionData调用GetState()把磁盘上的真实设置读入Output再以紧凑 JSON 打印到标准输出。写入/应用配置set# 为模块设置期望配置 $input {settings:{...}} PowerToys.DSC.exe set --resource settings --module FancyZones --input $inputset的底层实现值得展开见 SettingsResource.cs若--input为空直接输出错误错误消息走 stderr格式见 BaseResource.cs并返回失败反序列化输入到Input先读取当前状态到Output只在实际状态与期望状态不同时才真正写入先TestState()判断相等则跳过SetState()实现幂等输出应用后的完整设置 JSON并额外输出一份差异 JSONdiff标注发生变化的属性路径。关于设置文件的具体读写[SettingsFunctionData1.cs](https://link.gitcode.com/i/c2c1da6eb204be31598695e7af07e5d9) 中通过SettingsUtils.GetSettingsOrDefault读取、SettingsUtils.SaveSettings写回说明 DSC 最终操作的就是 PowerToys 各模块的settings.json 配置文件。校验配置是否漂移test# 校验当前状态是否与期望状态一致 $input {settings:{...}} PowerToys.DSC.exe test --resource settings --module FancyZones --input $inputtest的输出 JSON 中包含一个_inDesiredState字段参见 SettingsResource.cs为true表示当前配置与期望一致为false表示存在差异。判断逻辑在TestState()中实现——将输入设置与当前设置序列化后用JsonNode.DeepEquals做深度比较见 SettingsFunctionData1.cs 文件。这一特性非常适合在 CI 或开机脚本中做配置漂移检测。生成设置 JSON Schema# 获取某个模块设置的 JSON Schema描述所有可配置属性与类型 PowerToys.DSC.exe schema --resource settings --module FancyZonesSchema 对摸清这个模块到底能配哪些字段极其实用配合编辑器提示可以写出合法配置。文档与 SchemaCommand.cs 保持一致底层经由SettingsFunctionData.Schema()调用通用 Schema 生成器相关生成逻辑位于 PowerToys.Settings.DSC.Schema.Generator把设置类型反射为 JSON Schema。生成 DSC 资源清单manifest# 为指定模块生成资源清单并写入目录 $outputDir C:\manifests PowerToys.DSC.exe manifest --resource settings --module FancyZones --outputDir $outputDir # 为全部模块生成资源清单 PowerToys.DSC.exe manifest --resource settings --outputDir $outputDir省略--outputDir时清单直接打印到控制台# 打印清单到控制台不传 --outputDir PowerToys.DSC.exe manifest --resource settings --module AwakeManifest 是 DSC v3 资源发现机制的关键PowerToys 通过它声明每个ModuleSettings资源支持哪些方法get/set/test/export/schema。查看 SettingsResource.cs 可以发现写入磁盘的清单文件遵循microsoft.powertoys.模块名.settings.dsc.resource.json的命名并分别用stdin 方法JSON 输入方法命令方法声明各操作的 CLI 调用如set通过--input传参并声明implementsPretest: true与stateAndDiff: true这正是方式二/方式三中 DSC、WinGet 能够调用 PowerToys 资源的协议基础。若输出目录不可写命令会打印错误并返回失败。输入 JSON 结构约定不管用哪种方式下发配置settings资源的 JSON/YAML 结构都遵循同一约定以 Awake 为例{ settings: { properties: { keepDisplayOn: true, mode: 1 }, name: Awake, version: 0.0.1 } }字段说明settings.properties实际要配置的属性键值对键名与 Settings.UI.Library 中各模块设置类的公开属性一致如 FancyZones 的fancyzones_shiftDrag、ColorPicker 的copiedcolorrepresentationsettings.name模块名一般与--module/资源类型中的模块名一致如Awake、FancyZones、Appsettings.version设置结构版本号用于标识该模块设置约定的版本不同模块版本值不同如 Awake 使用0.0.1、FancyZones 使用1.0test/set命令的响应会额外包含_inDesiredState与差异信息便于脚本自动化判断是否需要修复。模块级属性差异也会体现在 diff 输出中。典型示例从单模块到全量备份下面按从简到繁给出四类开箱即用的示例完整覆盖 Settings Resource Examples 中的场景可直接复制改造。示例 1启用并配置 FancyZones直接执行先读取当前状态再构造期望状态并应用# 读取当前 FancyZones 配置。 $current PowerToys.DSC.exe get --resource settings --module FancyZones | ConvertFrom-Json # 构造期望配置开启 Shift 拖拽贴靠、跨屏拖动窗口跟随。 $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示例 2一份 DSC 文档配置多个工具把启用哪些工具 各工具参数合并成单个 DSC 配置文档# 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其中App模块的Enabled属性可控制各工具的启停见 App 模块文档启动项startup默认true、提权运行run_elevated默认false、主题theme可选light/dark/system。执行dsc config set --file powertoys-multi.dsc.yaml示例 3WinGet 安装 全套配置在全新机器上同时完成安装与配置适合做开发机/演示机基线# 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示例 4检测配置漂移并自动修复适合写进登录脚本或定时任务先test不一致再set修复。# 定义期望状态。 $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即可把整套 PowerToys 配置备份为一份 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落地建议与边界说明配置即代码把上述 YAML/JSON 与备份文件放入 Git 等版本库配合test命令可在任意机器上随时核对漂移实现可审计的 PowerToys 环境基线。善用 schema 探索属性对某个模块属性不确定时先用PowerToys.DSC.exe schema --resource settings --module ModuleName拿到完整字段定义字段类型、取值范围等再编写配置可大幅降低写错键名的概率。注意模块覆盖范围目前仅settings一个资源、25 个受支持模块MouseWithoutBorders、PowerLauncher、NewPlus 因敏感信息或绝对路径不可移植性被排除依据 SettingsResource.cs 源码注释。本文中所有命令、属性与示例均以本仓库2025-10-18 修订的文档版本为准。分层落地路径单机临时调整用PowerToys.DSC.exe直接执行需要可复用的标准配置用 DSC v3 YAMLdsc config set要装机即到位则选择 WinGet Configurationwinget configure。三者的底层都收敛到同一个settings资源。仓库内延伸阅读PowerToys DSC Overview本指南的官方来源文档Settings Resource Referencesettings资源的完整参考含各操作与 5 个完整示例模块文档目录25 个模块各自的属性、类型、默认值与分场景示例例如 App、Awake、FancyZones、ImageResizer核心实现PowerToys.DSC 主程序与命令注册settings 资源实现模块映射、get/set/test/schema/manifest 逻辑、被排除模块注释命令基类与公共选项--module/--resource/--input解析与模块校验资源对象/函数数据模型状态比较、差异计算与 Schema 生成单元测试PowerToys.DSC.UnitTests 中覆盖了App、Awake、ColorPicker、AdvancedPaste、AlwaysOnTop、CropAndLock等模块的SettingsResource*ModuleTest与通用命令测试可作为理解各操作语义的参考生成工具PowerToys.Settings.DSC.Schema.Generator 负责从设置类型生成 Schema、清单与示例官方示例配置Microsoft.PowerToys.Configure/examples含installAndConfiguration.winget、enableAllModules.winget、disableAllModules.winget等可直接借鉴的 winget 配置。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerToys DSC 配置指南：用 Desired State Configuration 将 PowerToys 各工具设置声明式地纳入代码管理与批量自动化
PowerToys DSC 配置指南用 Desired State Configuration 将 PowerToys 各工具设置声明式地纳入代码管理与批量自动化【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToysPowerToys 官方基于 Microsoft Desired State ConfigurationDSCv3 提供了PowerToys DSC支持通过PowerToys.DSC.exe命令行工具与settings资源配置资源把 Awake、FancyZones、ImageResizer 等所有工具的设置变成可声明、可测试、可回滚的配置即代码。本文以 PowerToys DSC Overview 为骨架结合仓库源码完整讲解三种使用方式PowerToys.DSC.exe直接执行、标准 DSC v3 配置文档、WinGet Configuration、全部 CLI 操作、支持的模块与资源清单并给出可直接复制的端到端示例帮助你在多机环境统一管控 PowerToys 配置。DSC 是什么PowerToys 的声明式配置管理入口PowerToys DSCDesired State Configuration期望状态配置允许你描述PowerToys 应当处于什么配置状态而不是手动逐个点击设置界面。核心能力包括声明并强制执行PowerToys 各实用工具模块的期望配置状态跨多台系统自动化同步 PowerToys 配置告别逐台手工调整与 WinGet 及其他 DSC 兼容工具集成在安装包的同时落地配置将 PowerToys 设置作为代码纳入版本控制实现可审计、可复现的环境基线。PowerToys 的 DSC 实现对外暴露一个名为settings的资源resource统一管理所有 PowerToys 工具模块的配置每个工具可独立配置从而实现对整个 PowerToys 环境的细粒度控制。从源码角度印证settings资源在 SettingsResource.cs 中定义内部通过Dictionarystring, Funcstring?, ISettingsFunctionData把每个模块名映射到各自的设置类型如AwakeSettings、FancyZonesSettings并默认回落到App模块见ModuleOrDefault属性。而命令行入口 Program.cs 使用System.CommandLine注册了 7 个子命令get、set、export、test、schema、manifest、modules。三种使用方式PowerToys DSC 可以在三个层面被使用从单条命令手动操作到完整 YAML 配置文档托管按需选择即可。方式一使用 PowerToys.DSC.exe 直接执行在已安装 PowerToys 的环境里直接调用PowerToys.DSC.exe完成查询、设置与校验。基本语法为PowerToys.DSC.exe 命令 --resource settings --module 模块名 [--input JSON]。# 读取某个模块的当前配置 PowerToys.DSC.exe get --resource settings --module Awake # 向某个模块写入配置--input 传入 JSON 字符串 $input {settings:{...}} PowerToys.DSC.exe set --resource settings --module Awake --input $input # 校验当前配置是否等于期望配置test PowerToys.DSC.exe test --resource settings --module Awake --input $input从 BaseCommand.cs 可知所有子命令共享--module、--resource、--input三个选项并且命令执行前会先校验--module是否属于该资源支持的模块列表不支持的模块会直接报错并以退出码 1 结束。各子命令的完整用法见下文常用操作章节。方式二Microsoft DSC v3 标准配置文档把配置写成标准的 DSC v3 YAML 文档然后用dsc命令行应用。PowerToys 的资源类型按模块名Settings命名如Microsoft.PowerToys/AwakeSettings并被注册到 DSC v3 中# 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需要说明YAML 里type名称与模块文档一一对应且settings属性块内的name通常与模块名一致、version为该模块设置结构的版本号。资源类型实际由manifest命令生成命名格式见下文PowerToys 安装包中会携带这些资源清单以支持 DSC v3 协议调用。方式三WinGet Configuration 一体化把安装 PowerToys和配置工具写进同一个 WinGet 配置文档实现装机即到位# 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应用该文档时使用winget configure winget-powertoys.yaml或dsc config set --file ...。仓库中还提供了同类 winget 示例文件可供对照例如 installAndConfiguration.winget它演示了通过Microsoft.WinGet.DSC/WinGetPackage安装、再通过资源配置FancyZones、ImageResizer等模块的写法。可用资源ResourcePowerToys DSC 目前对外提供以下资源资源说明settings管理 PowerToys 各工具模块的配置settings资源内部把每个工具视为独立模块分别管理。在 SettingsResource.cs 中可以确认资源名常量ResourceName settings。该资源支持标准 DSC 操作get、set、test、export、schema与manifest生成。详细参考见 Settings Resource Reference。可用模块Modules总览settings资源支持配置以下 PowerToys 工具。下表同时给出各模块的详细属性文档位于doc/dsc/modules/目录可点击深入了解每个模块的可配置属性、类型、默认值与示例。模块说明详细文档AppPowerToys 应用级通用设置工具启停、开机启动、主题等App 模块AdvancedPaste高级剪贴板/粘贴操作AdvancedPaste 模块AlwaysOnTop窗口置顶AlwaysOnTop 模块Awake保持电脑唤醒Awake 模块ColorPicker全局取色器ColorPicker 模块CropAndLock裁剪并锁定窗口区域CropAndLock 模块EnvironmentVariables管理环境变量EnvironmentVariables 模块FancyZones窗口布局管理FancyZones 模块FileLocksmith定位占用文件的进程FileLocksmith 模块FindMyMouse定位鼠标光标FindMyMouse 模块Hosts快速编辑 hosts 文件Hosts 模块ImageResizer右键菜单批量改图尺寸ImageResizer 模块KeyboardManager按键重映射与快捷键KeyboardManager 模块MeasureTool屏幕像素测量MeasureTool 模块MouseHighlighter高亮鼠标光标MouseHighlighter 模块MouseJump大屏/多屏间快速跳转鼠标MouseJump 模块MousePointerCrosshairs鼠标居中十字准星MousePointerCrosshairs 模块Peek快速文件预览Peek 模块PowerAccent快速插入带音调字符PowerAccent 模块PowerOCR从图片提取文字PowerOCR 模块PowerRename批量重命名PowerRename 模块RegistryPreview可视化编辑注册表文件RegistryPreview 模块ShortcutGuide显示 Windows 快捷键指南ShortcutGuide 模块Workspaces应用窗口集的保存与恢复Workspaces 模块ZoomIt屏幕缩放与标注ZoomIt 模块值得注意的是settings资源并不支持所有PowerToys 模块。查看 SettingsResource.cs 中的源码注释可以发现当前明确被排除的模块包括MouseWithoutBorders配置中含敏感信息导入/导出可能存在安全隐患PowerLauncher设置中保存了绝对文件路径跨机器不可移植NewPlus同样使用绝对文件路径不可移植。如果你计划用 PowerToys DSC 做大规模部署应提前确认目标配置确实落在这 25 个受支持模块范围内。常用操作PowerToys.DSC.exe 命令详解以下命令均可在 PowerShell 中直接执行PowerToys.DSC.exe随 PowerToys 安装建议在安装目录或将其加入 PATH 后调用。这些操作与 settings-resource.md 中描述的 DSC 行为一一对应底层均由各*Command.cs转发给SettingsResource处理。列出全部受支持模块PowerToys.DSC.exe modules --resource settings该命令对应源码 ModulesCommand.cs它调用GetSupportedModules()返回按名称排序的模块列表——即上表列出的 25 个模块。读取当前配置get / export# 读取指定模块的当前配置 PowerToys.DSC.exe get --resource settings --module FancyZones # 导出配置与 get 输出完全一致 PowerToys.DSC.exe export --resource settings --module FancyZones从源码看get与export行为等价——SettingsResource.cs 中GetState()直接复用了ExportState()的逻辑先创建该模块的 FunctionData调用GetState()把磁盘上的真实设置读入Output再以紧凑 JSON 打印到标准输出。写入/应用配置set# 为模块设置期望配置 $input {settings:{...}} PowerToys.DSC.exe set --resource settings --module FancyZones --input $inputset的底层实现值得展开见 SettingsResource.cs若--input为空直接输出错误错误消息走 stderr格式见 BaseResource.cs并返回失败反序列化输入到Input先读取当前状态到Output只在实际状态与期望状态不同时才真正写入先TestState()判断相等则跳过SetState()实现幂等输出应用后的完整设置 JSON并额外输出一份差异 JSONdiff标注发生变化的属性路径。关于设置文件的具体读写[SettingsFunctionData1.cs](https://link.gitcode.com/i/c2c1da6eb204be31598695e7af07e5d9) 中通过SettingsUtils.GetSettingsOrDefault读取、SettingsUtils.SaveSettings写回说明 DSC 最终操作的就是 PowerToys 各模块的settings.json 配置文件。校验配置是否漂移test# 校验当前状态是否与期望状态一致 $input {settings:{...}} PowerToys.DSC.exe test --resource settings --module FancyZones --input $inputtest的输出 JSON 中包含一个_inDesiredState字段参见 SettingsResource.cs为true表示当前配置与期望一致为false表示存在差异。判断逻辑在TestState()中实现——将输入设置与当前设置序列化后用JsonNode.DeepEquals做深度比较见 SettingsFunctionData1.cs 文件。这一特性非常适合在 CI 或开机脚本中做配置漂移检测。生成设置 JSON Schema# 获取某个模块设置的 JSON Schema描述所有可配置属性与类型 PowerToys.DSC.exe schema --resource settings --module FancyZonesSchema 对摸清这个模块到底能配哪些字段极其实用配合编辑器提示可以写出合法配置。文档与 SchemaCommand.cs 保持一致底层经由SettingsFunctionData.Schema()调用通用 Schema 生成器相关生成逻辑位于 PowerToys.Settings.DSC.Schema.Generator把设置类型反射为 JSON Schema。生成 DSC 资源清单manifest# 为指定模块生成资源清单并写入目录 $outputDir C:\manifests PowerToys.DSC.exe manifest --resource settings --module FancyZones --outputDir $outputDir # 为全部模块生成资源清单 PowerToys.DSC.exe manifest --resource settings --outputDir $outputDir省略--outputDir时清单直接打印到控制台# 打印清单到控制台不传 --outputDir PowerToys.DSC.exe manifest --resource settings --module AwakeManifest 是 DSC v3 资源发现机制的关键PowerToys 通过它声明每个ModuleSettings资源支持哪些方法get/set/test/export/schema。查看 SettingsResource.cs 可以发现写入磁盘的清单文件遵循microsoft.powertoys.模块名.settings.dsc.resource.json的命名并分别用stdin 方法JSON 输入方法命令方法声明各操作的 CLI 调用如set通过--input传参并声明implementsPretest: true与stateAndDiff: true这正是方式二/方式三中 DSC、WinGet 能够调用 PowerToys 资源的协议基础。若输出目录不可写命令会打印错误并返回失败。输入 JSON 结构约定不管用哪种方式下发配置settings资源的 JSON/YAML 结构都遵循同一约定以 Awake 为例{ settings: { properties: { keepDisplayOn: true, mode: 1 }, name: Awake, version: 0.0.1 } }字段说明settings.properties实际要配置的属性键值对键名与 Settings.UI.Library 中各模块设置类的公开属性一致如 FancyZones 的fancyzones_shiftDrag、ColorPicker 的copiedcolorrepresentationsettings.name模块名一般与--module/资源类型中的模块名一致如Awake、FancyZones、Appsettings.version设置结构版本号用于标识该模块设置约定的版本不同模块版本值不同如 Awake 使用0.0.1、FancyZones 使用1.0test/set命令的响应会额外包含_inDesiredState与差异信息便于脚本自动化判断是否需要修复。模块级属性差异也会体现在 diff 输出中。典型示例从单模块到全量备份下面按从简到繁给出四类开箱即用的示例完整覆盖 Settings Resource Examples 中的场景可直接复制改造。示例 1启用并配置 FancyZones直接执行先读取当前状态再构造期望状态并应用# 读取当前 FancyZones 配置。 $current PowerToys.DSC.exe get --resource settings --module FancyZones | ConvertFrom-Json # 构造期望配置开启 Shift 拖拽贴靠、跨屏拖动窗口跟随。 $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示例 2一份 DSC 文档配置多个工具把启用哪些工具 各工具参数合并成单个 DSC 配置文档# 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其中App模块的Enabled属性可控制各工具的启停见 App 模块文档启动项startup默认true、提权运行run_elevated默认false、主题theme可选light/dark/system。执行dsc config set --file powertoys-multi.dsc.yaml示例 3WinGet 安装 全套配置在全新机器上同时完成安装与配置适合做开发机/演示机基线# 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示例 4检测配置漂移并自动修复适合写进登录脚本或定时任务先test不一致再set修复。# 定义期望状态。 $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即可把整套 PowerToys 配置备份为一份 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落地建议与边界说明配置即代码把上述 YAML/JSON 与备份文件放入 Git 等版本库配合test命令可在任意机器上随时核对漂移实现可审计的 PowerToys 环境基线。善用 schema 探索属性对某个模块属性不确定时先用PowerToys.DSC.exe schema --resource settings --module ModuleName拿到完整字段定义字段类型、取值范围等再编写配置可大幅降低写错键名的概率。注意模块覆盖范围目前仅settings一个资源、25 个受支持模块MouseWithoutBorders、PowerLauncher、NewPlus 因敏感信息或绝对路径不可移植性被排除依据 SettingsResource.cs 源码注释。本文中所有命令、属性与示例均以本仓库2025-10-18 修订的文档版本为准。分层落地路径单机临时调整用PowerToys.DSC.exe直接执行需要可复用的标准配置用 DSC v3 YAMLdsc config set要装机即到位则选择 WinGet Configurationwinget configure。三者的底层都收敛到同一个settings资源。仓库内延伸阅读PowerToys DSC Overview本指南的官方来源文档Settings Resource Referencesettings资源的完整参考含各操作与 5 个完整示例模块文档目录25 个模块各自的属性、类型、默认值与分场景示例例如 App、Awake、FancyZones、ImageResizer核心实现PowerToys.DSC 主程序与命令注册settings 资源实现模块映射、get/set/test/schema/manifest 逻辑、被排除模块注释命令基类与公共选项--module/--resource/--input解析与模块校验资源对象/函数数据模型状态比较、差异计算与 Schema 生成单元测试PowerToys.DSC.UnitTests 中覆盖了App、Awake、ColorPicker、AdvancedPaste、AlwaysOnTop、CropAndLock等模块的SettingsResource*ModuleTest与通用命令测试可作为理解各操作语义的参考生成工具PowerToys.Settings.DSC.Schema.Generator 负责从设置类型生成 Schema、清单与示例官方示例配置Microsoft.PowerToys.Configure/examples含installAndConfiguration.winget、enableAllModules.winget、disableAllModules.winget等可直接借鉴的 winget 配置。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考