PowerToys 如何基于模块模板创建一个新 PowerToy 并接入设置与安装器【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys当你决定给 PowerToys 贡献一个新功能模块时需要完成一条完整链路从模块模板生成工程骨架、实现模块接口Interface DLL、把模块注册进 Runner、在设置应用中加上专属设置页最后把它纳入 WiX 安装器。本文按 Creating a new PowerToy 开发指南 的路径展开配合 模块模板说明、调试文档 和 安装器目录给出每一步的操作位置、需要修改的文件和最终验证方式。适用对象是已经能构建并运行PowerToys.slnx的 Windows 开发者。1. 准备条件先保证现有代码能构建、能调试在动手之前按 Getting Started 与调试指南 完成环境准备Fork 仓库并克隆到本机进入仓库根目录运行git submodule update --init --recursive初始化所有子模块进入.config目录执行winget configure .\configuration.vsEnterprise.winget选择与你 Visual Studio 发行版匹配的配置。完成后确认PowerToys.slnx可以完整构建并跑起来。若要在 Visual Studio 外构建整包可在Developer Command Prompt for VS中执行平台按需改为 x64/ARM64msbuild -restore -p:RestorePackagesConfigtrue -p:PlatformARM64 -m PowerToys.slnx /tl /p:NuGetInteractivetrue新模块可选依赖 WiX v5 工具链用于后面第 6 节的安装器工作。2. 安装模块模板并生成新模块工程模板位于仓库的 tools/project_template包含现成的ModuleTemplate工程dllmain.cpp、pch.h、resource.h、$projectname$.rc等默认名占位符为$projectname$VS 创建工程时会自动替换。安装方式来自模板 README把ModuleTemplate.zip放进用户模板目录VS 2022 用%USERPROFILE%\Documents\Visual Studio 2022\Templates\ProjectTemplates\VS 2026 用%USERPROFILE%\Documents\Visual Studio 18\Templates\ProjectTemplates\在 Visual Studio 新建项目时Visual C分类下会出现该模板用模板创建工程后把新工程放到src\modules\目录下保证相对路径全部有效。模板生成后需要做的机械替换更新所有工程名和命名空间为你的模块名更新.vcxproj和 solution 文件中的 GUID。仓库中的 tools/project_template/ModuleTemplate 源码工程本身是“不可直接编译”的模板源仓库通过ModuleTemplateCompileTest.vcxproj挂进PowerToys.slnx来保证模板源码可持续编译你不需要改动它。3. 实现模块接口关键虚函数逐项确认模块接口是 Runner 与新模块交互的标准入口背景见 PowerToys 架构文档 的 Module Interface Overview 一节。模板dllmain.cpp里大部分类函数只需做字符串替换以下函数需要写实际逻辑ModuleSettings结构体定义你的设置项字符串、bool、int、自定义枚举gpo_policy_enabled_configuration()返回powertoys_gpo::getConfiguredModuleEnabledValue()模块必须挂进 GPO 设置列表否则管理员无法通过网络组策略管控该模块init_settings()从settings.json读取已有配置不存在则用默认值get_config(wchar_t* buffer, int* buffer_size)把当前配置序列化为 JSON 返回给设置应用set_config(const wchar_t* config)解析并落盘设置应用传来的新配置call_custom_action(const wchar_t* action)响应设置应用发来的自定义动作例如打开你的自定义编辑器生命周期enable()启动模块、disable()停止并清理、is_enabled()、is_enabled_by_default()决定是否随应用默认启用热键如模块有快捷键parse_hotkey(...)把设置中的热键转成接口内部格式、get_hotkeys(Hotkey*, size_t)、on_hotkey(size_t hotkeyId)。接口层还有一套完整的设置控件 API模板 README 给出了可直接参考的示例add_bool_toggle、add_int_spinner、add_string、add_color_picker、add_custom_action生成设置项PowerToyValues::from_json_string/load_from_settings_file/save_to_settings_file负责解析、读取和持久化。设置文件默认落在用户目录%LocalAppData%\Microsoft\PowerToys下每个 PowerToy 一个独立文件夹。模块 ID 不一致是加载失败最常见的原因之一manifest、注册表和服务中的 ID 必须保持一致开发指南原文提示。4. 把模块注册进 RunnerRunner 负责加载各模块 DLLsrc/runner/powertoy_module.cpp 中通过LoadLibraryW载入接口 DLL并按 DLL 名分发事件。要让 Runner 认识你的模块需要把它加进下列文件中的注册列表——搜索其它已有模块名可以很快定位到这些列表src/runner/modules.hsrc/runner/modules.cppsrc/runner/resource.hsrc/runner/settings_window.hsrc/runner/settings_window.cppsrc/runner/main.cpp其中包含known_dlls映射表新模块的 DLL 名必须加入否则运行时无法加载src/common/logger.h接入日志ModuleInterface 工程的产物ModuleInterface.dll就是 Runner 实际加载的对象构建配置要指向正确的输出目录。5. 编写模块服务与接口分开的项目接口之外模块的主体逻辑是另一个独立工程可以用 C 也可以 C# 编写混合示例见架构文档中的 PowerRename 场景服务名在.vcxproj的TargetName中设置例如TargetNamePowerToys.LightSwitchService/TargetName查看.vcxproj内容需要先右键工程选择Unload project图标在.rc文件中设置服务内部读取设置使用ModuleSettings.h该文件随服务工程存放可从 LightSwitch 等模块复制再改造ModuleSettings::instance().InitFileWatcher(); ModuleSettings::instance().LoadSettings(); auto settings ModuleSettings::instance().settings();如果模块带界面开发指南要求使用 WinUI 3 框架不是 UWP新建工程时选 WinUI Blank App 模板从非 UI 线程更新界面时要用DispatcherQueue。6. 接入设置应用Properties、ViewModel 与 XAML 页面PowerToys 的设置以每模块 JSON 的形式保存在%LOCALAPPDATA%\Microsoft\PowerToys\module\settings.json按指南设置页需要四处改动均以module替换为你的模块名在src\settings-ui\Settings.UI.Library\新建moduleProperties.cs——定义全部设置的默认值每一项都要在此出现且与模块接口里的定义一致同目录新建moduleSettings.cs——settings.json由它构建构造函数结构形如public ModuleSettings() { Name ModuleName; Version Assembly.GetExecutingAssembly().GetName().Version.ToString(); Properties new ModuleProperties(); // 上面定义的设置属性 }在src\settings-ui\Settings.UI\ViewModels新建moduleViewModel.cs——这是设置页面与磁盘 settings 文件之间的桥梁属性变化通过NotifyPropertyChanged触发设置监听在src\settings-ui\Settings.UI\SettingsXAML\Views新建SettingsPage.xaml——用户在设置应用里看到的页面。页面中面向用户的文案必须走资源字符串以便本地化x:Uid指向Resources.resw中的条目后缀按控件属性变化如.Content、.Text、.HeaderComboBoxItem x:UidLightSwitch_ModeOff AutomationProperties.AutomationIdOffCBItem_LightSwitch TagOff /data nameLightSwitch_ModeOff.Content xml:spacepreserve valueOff/value /data注意指南强调用外部编辑器VS Code、记事本手工改 settings 文件不会触发设置监听器只有经由 PowerToys 写入的变更才会触发重载。7. 接入 WiX 安装器安装器代码在 installer 目录下模块需要四步才能被打进安装包通过 NuGet 安装WixToolset.HeatWix5 工具在installer\PowerToysInstallerVNext中新增Module.wxs格式照抄现有模块如 LightSwitch再替换字符串与 GUIDModule.wxs中的!--ModuleNameFiles_Component_Def--是占位注释文件组件由 installer/generateAllFileComponents.ps1 生成后填回不要手填在 installer/Product.wxs 的Feature IdCoreFeature ... 区块加一行引用形态类似ComponentGroupRef IdModuleComponentGroup /在生成脚本末尾按以下格式追加两行-fileListName ModuleFiles要与你Module.wxs中设置的字符串一致ModuleServiceName要与服务 exe 名一致Generate-FileList -fileDepsJson -fileListName ModuleFiles -wxsFilePath $PSScriptRoot\Module.wxs -depsPath $PSScriptRoot..\..\..\$platform\Release\ModuleServiceName Generate-FileComponents -fileListName ModuleFiles -wxsFilePath $PSScriptRoot\Module.wxs -regroot $registryroot其中$platform由脚本运行时的平台参数决定。若模块附带子目录资源如图标文件可参考PowerToysSvgs组件的做法。8. 构建、调试与结果验证验证链路分三段1. 调试验证。按 调试文档 的 Pre-Debugging Setup 完成后把runner设为启动工程构建配置与系统架构 x64/ARM64 匹配F5 启动 PowerToys Runner要给服务打断点按 CtrlAltP 搜索你的服务进程附加到调试器。2. 日志验证。确认模块初始化成功看两处日志%LOCALAPPDATA%\Microsoft\PowerToys\RunnerLogsRunner 侧%LOCALAPPDATA%\Microsoft\PowerToys\Module\Service\version你的模块version替换为实际版本号。3. 设置应用验证。指南给出的手工验证清单在 PowerToys Settings 中启用/禁用你的模块确认日志中有初始化记录确认图标、tooltip 与 OOBE 页面显示正常。构建异常的兜底。文档提示 PowerToys 会激进缓存.nuget产物构建行为异常时清理后重建也可用文档给出的命令msbuild PowerToys.slnx /t:Clean /p:Platformx64 /p:ConfigurationDebug后删掉x64/、ARM64/、packages/等输出目录再重建。9. 收尾与限制模块基本完成后还有几项文档要求的收尾工作OOBE 页面在src\settings-ui\Settings.UI\SettingsXAML\OOBE\Views新建OOBEModuleName.xaml并把模块名加入 src/settings-ui/Settings.UI/OOBE/Enums/PowerToysModules.cs 中的枚举快捷键冲突检测模块若带快捷键需按 设置实现文档 的 shortcut conflict detection 一节注册开发者文档在doc/devdocs/modules/下补一份说明架构、关键文件与调试要点的模块文档。两条明确的限制要记住设置监听只对经 PowerToys 写入的变更生效接口 ID、DLL 名、.wxs文件名、脚本中的fileListName必须逐一对齐任何一处错位都会表现为模块加载失败或安装器缺文件。完成上述步骤后你的模块应当表现为Runner 能加载ModuleInterface.dll、设置应用中出现可交互的设置页且修改能落盘到settings.json、WiX 生成的安装包中包含你的模块文件——三者都成立说明模板到安装器的接入链路已打通。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerToys 如何基于模块模板创建一个新 PowerToy 并接入设置与安装器
PowerToys 如何基于模块模板创建一个新 PowerToy 并接入设置与安装器【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys当你决定给 PowerToys 贡献一个新功能模块时需要完成一条完整链路从模块模板生成工程骨架、实现模块接口Interface DLL、把模块注册进 Runner、在设置应用中加上专属设置页最后把它纳入 WiX 安装器。本文按 Creating a new PowerToy 开发指南 的路径展开配合 模块模板说明、调试文档 和 安装器目录给出每一步的操作位置、需要修改的文件和最终验证方式。适用对象是已经能构建并运行PowerToys.slnx的 Windows 开发者。1. 准备条件先保证现有代码能构建、能调试在动手之前按 Getting Started 与调试指南 完成环境准备Fork 仓库并克隆到本机进入仓库根目录运行git submodule update --init --recursive初始化所有子模块进入.config目录执行winget configure .\configuration.vsEnterprise.winget选择与你 Visual Studio 发行版匹配的配置。完成后确认PowerToys.slnx可以完整构建并跑起来。若要在 Visual Studio 外构建整包可在Developer Command Prompt for VS中执行平台按需改为 x64/ARM64msbuild -restore -p:RestorePackagesConfigtrue -p:PlatformARM64 -m PowerToys.slnx /tl /p:NuGetInteractivetrue新模块可选依赖 WiX v5 工具链用于后面第 6 节的安装器工作。2. 安装模块模板并生成新模块工程模板位于仓库的 tools/project_template包含现成的ModuleTemplate工程dllmain.cpp、pch.h、resource.h、$projectname$.rc等默认名占位符为$projectname$VS 创建工程时会自动替换。安装方式来自模板 README把ModuleTemplate.zip放进用户模板目录VS 2022 用%USERPROFILE%\Documents\Visual Studio 2022\Templates\ProjectTemplates\VS 2026 用%USERPROFILE%\Documents\Visual Studio 18\Templates\ProjectTemplates\在 Visual Studio 新建项目时Visual C分类下会出现该模板用模板创建工程后把新工程放到src\modules\目录下保证相对路径全部有效。模板生成后需要做的机械替换更新所有工程名和命名空间为你的模块名更新.vcxproj和 solution 文件中的 GUID。仓库中的 tools/project_template/ModuleTemplate 源码工程本身是“不可直接编译”的模板源仓库通过ModuleTemplateCompileTest.vcxproj挂进PowerToys.slnx来保证模板源码可持续编译你不需要改动它。3. 实现模块接口关键虚函数逐项确认模块接口是 Runner 与新模块交互的标准入口背景见 PowerToys 架构文档 的 Module Interface Overview 一节。模板dllmain.cpp里大部分类函数只需做字符串替换以下函数需要写实际逻辑ModuleSettings结构体定义你的设置项字符串、bool、int、自定义枚举gpo_policy_enabled_configuration()返回powertoys_gpo::getConfiguredModuleEnabledValue()模块必须挂进 GPO 设置列表否则管理员无法通过网络组策略管控该模块init_settings()从settings.json读取已有配置不存在则用默认值get_config(wchar_t* buffer, int* buffer_size)把当前配置序列化为 JSON 返回给设置应用set_config(const wchar_t* config)解析并落盘设置应用传来的新配置call_custom_action(const wchar_t* action)响应设置应用发来的自定义动作例如打开你的自定义编辑器生命周期enable()启动模块、disable()停止并清理、is_enabled()、is_enabled_by_default()决定是否随应用默认启用热键如模块有快捷键parse_hotkey(...)把设置中的热键转成接口内部格式、get_hotkeys(Hotkey*, size_t)、on_hotkey(size_t hotkeyId)。接口层还有一套完整的设置控件 API模板 README 给出了可直接参考的示例add_bool_toggle、add_int_spinner、add_string、add_color_picker、add_custom_action生成设置项PowerToyValues::from_json_string/load_from_settings_file/save_to_settings_file负责解析、读取和持久化。设置文件默认落在用户目录%LocalAppData%\Microsoft\PowerToys下每个 PowerToy 一个独立文件夹。模块 ID 不一致是加载失败最常见的原因之一manifest、注册表和服务中的 ID 必须保持一致开发指南原文提示。4. 把模块注册进 RunnerRunner 负责加载各模块 DLLsrc/runner/powertoy_module.cpp 中通过LoadLibraryW载入接口 DLL并按 DLL 名分发事件。要让 Runner 认识你的模块需要把它加进下列文件中的注册列表——搜索其它已有模块名可以很快定位到这些列表src/runner/modules.hsrc/runner/modules.cppsrc/runner/resource.hsrc/runner/settings_window.hsrc/runner/settings_window.cppsrc/runner/main.cpp其中包含known_dlls映射表新模块的 DLL 名必须加入否则运行时无法加载src/common/logger.h接入日志ModuleInterface 工程的产物ModuleInterface.dll就是 Runner 实际加载的对象构建配置要指向正确的输出目录。5. 编写模块服务与接口分开的项目接口之外模块的主体逻辑是另一个独立工程可以用 C 也可以 C# 编写混合示例见架构文档中的 PowerRename 场景服务名在.vcxproj的TargetName中设置例如TargetNamePowerToys.LightSwitchService/TargetName查看.vcxproj内容需要先右键工程选择Unload project图标在.rc文件中设置服务内部读取设置使用ModuleSettings.h该文件随服务工程存放可从 LightSwitch 等模块复制再改造ModuleSettings::instance().InitFileWatcher(); ModuleSettings::instance().LoadSettings(); auto settings ModuleSettings::instance().settings();如果模块带界面开发指南要求使用 WinUI 3 框架不是 UWP新建工程时选 WinUI Blank App 模板从非 UI 线程更新界面时要用DispatcherQueue。6. 接入设置应用Properties、ViewModel 与 XAML 页面PowerToys 的设置以每模块 JSON 的形式保存在%LOCALAPPDATA%\Microsoft\PowerToys\module\settings.json按指南设置页需要四处改动均以module替换为你的模块名在src\settings-ui\Settings.UI.Library\新建moduleProperties.cs——定义全部设置的默认值每一项都要在此出现且与模块接口里的定义一致同目录新建moduleSettings.cs——settings.json由它构建构造函数结构形如public ModuleSettings() { Name ModuleName; Version Assembly.GetExecutingAssembly().GetName().Version.ToString(); Properties new ModuleProperties(); // 上面定义的设置属性 }在src\settings-ui\Settings.UI\ViewModels新建moduleViewModel.cs——这是设置页面与磁盘 settings 文件之间的桥梁属性变化通过NotifyPropertyChanged触发设置监听在src\settings-ui\Settings.UI\SettingsXAML\Views新建SettingsPage.xaml——用户在设置应用里看到的页面。页面中面向用户的文案必须走资源字符串以便本地化x:Uid指向Resources.resw中的条目后缀按控件属性变化如.Content、.Text、.HeaderComboBoxItem x:UidLightSwitch_ModeOff AutomationProperties.AutomationIdOffCBItem_LightSwitch TagOff /data nameLightSwitch_ModeOff.Content xml:spacepreserve valueOff/value /data注意指南强调用外部编辑器VS Code、记事本手工改 settings 文件不会触发设置监听器只有经由 PowerToys 写入的变更才会触发重载。7. 接入 WiX 安装器安装器代码在 installer 目录下模块需要四步才能被打进安装包通过 NuGet 安装WixToolset.HeatWix5 工具在installer\PowerToysInstallerVNext中新增Module.wxs格式照抄现有模块如 LightSwitch再替换字符串与 GUIDModule.wxs中的!--ModuleNameFiles_Component_Def--是占位注释文件组件由 installer/generateAllFileComponents.ps1 生成后填回不要手填在 installer/Product.wxs 的Feature IdCoreFeature ... 区块加一行引用形态类似ComponentGroupRef IdModuleComponentGroup /在生成脚本末尾按以下格式追加两行-fileListName ModuleFiles要与你Module.wxs中设置的字符串一致ModuleServiceName要与服务 exe 名一致Generate-FileList -fileDepsJson -fileListName ModuleFiles -wxsFilePath $PSScriptRoot\Module.wxs -depsPath $PSScriptRoot..\..\..\$platform\Release\ModuleServiceName Generate-FileComponents -fileListName ModuleFiles -wxsFilePath $PSScriptRoot\Module.wxs -regroot $registryroot其中$platform由脚本运行时的平台参数决定。若模块附带子目录资源如图标文件可参考PowerToysSvgs组件的做法。8. 构建、调试与结果验证验证链路分三段1. 调试验证。按 调试文档 的 Pre-Debugging Setup 完成后把runner设为启动工程构建配置与系统架构 x64/ARM64 匹配F5 启动 PowerToys Runner要给服务打断点按 CtrlAltP 搜索你的服务进程附加到调试器。2. 日志验证。确认模块初始化成功看两处日志%LOCALAPPDATA%\Microsoft\PowerToys\RunnerLogsRunner 侧%LOCALAPPDATA%\Microsoft\PowerToys\Module\Service\version你的模块version替换为实际版本号。3. 设置应用验证。指南给出的手工验证清单在 PowerToys Settings 中启用/禁用你的模块确认日志中有初始化记录确认图标、tooltip 与 OOBE 页面显示正常。构建异常的兜底。文档提示 PowerToys 会激进缓存.nuget产物构建行为异常时清理后重建也可用文档给出的命令msbuild PowerToys.slnx /t:Clean /p:Platformx64 /p:ConfigurationDebug后删掉x64/、ARM64/、packages/等输出目录再重建。9. 收尾与限制模块基本完成后还有几项文档要求的收尾工作OOBE 页面在src\settings-ui\Settings.UI\SettingsXAML\OOBE\Views新建OOBEModuleName.xaml并把模块名加入 src/settings-ui/Settings.UI/OOBE/Enums/PowerToysModules.cs 中的枚举快捷键冲突检测模块若带快捷键需按 设置实现文档 的 shortcut conflict detection 一节注册开发者文档在doc/devdocs/modules/下补一份说明架构、关键文件与调试要点的模块文档。两条明确的限制要记住设置监听只对经 PowerToys 写入的变更生效接口 ID、DLL 名、.wxs文件名、脚本中的fileListName必须逐一对齐任何一处错位都会表现为模块加载失败或安装器缺文件。完成上述步骤后你的模块应当表现为Runner 能加载ModuleInterface.dll、设置应用中出现可交互的设置页且修改能落盘到settings.json、WiX 生成的安装包中包含你的模块文件——三者都成立说明模板到安装器的接入链路已打通。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考