PowerToys Command Palette 扩展本地开发指南：从稀疏包签名到 CmdPal 热重载的完整循环

PowerToys Command Palette 扩展本地开发指南从稀疏包签名到 CmdPal 热重载的完整循环【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys导读本文面向需要在本地迭代 Microsoft.CmdPal.Ext.PowerToys 扩展代码的开发者完整讲解在 Windows 源码仓库中编译该 Command Palette 扩展并用稀疏包Sparse Package为其授予包标识的本地开发流程。读完本文你将掌握PackageIdentity项目如何产出带签名的PowerToysSparse.msix、为何扩展二进制必须落入WinUI3Apps\子目录、如何信任开发证书并执行Add-AppxPackage注册以及普通代码改动与清单改动分别应重做哪些步骤。背景为什么扩展需要一个稀疏包Command PaletteCmdPal通过 Windows 的 app extension 机制发现第三方命令提供者。扩展若要以 Win32full-trust进程形式承载并提供包标识就必须被一个已注册的 MSIX 包包装。在 PowerToys 仓库中这个身份载体是稀疏包Sparse Package——一种只包含清单、不含 payload 的 MSIX作用是仅授予包标识Package Identity实际可执行文件仍放在外部目录。仓库用 PackageIdentity/AppxManifest.xml 定义这个共享身份Identity NameMicrosoft.PowerToys.SparseApp ... Version0.0.1.0 /包名与版本本地构建时版本与发布者会被 BuildSparsePackage.ps1 依据src/Version.props和开发证书动态改写。该清单把多个 full-trust Win32 组件归入同一个Microsoft.PowerToys.SparseApp包括PowerToys.Settings.exe、PowerToys.ImageResizer.exe、PowerToys.AdvancedPaste.exe以及我们要迭代的Microsoft.CmdPal.Ext.PowerToys.exe。扩展所在ApplicationAppxManifest.xml声明了两件事ExecutableMicrosoft.CmdPal.Ext.PowerToys.exe该 exe 相对稀疏包的ExternalLocation即输出根目录下的WinUI3Apps\子文件夹解析一个windows.comServerClass Id7EC02C7D-8F98-4A2E-9F23-B58C2C2F2B17以及一个windows.appExtensioncom.microsoft.commandpalette/ IdPowerToys后者把 CmdPal 扩展的激活指向同一个 Class Id。因此稀疏包与扩展必须针对同一平台与配置构建例如同为x64\Debug否则清单中的相对路径无法解析到真实二进制。相关来源扩展本体是一个 C# WinExe见 Microsoft.CmdPal.Ext.PowerToys.csproj入口Main只在收到-RegisterProcessAsComServer参数时才进入 COM Server 模式见 Program.cs并用[Guid(7EC02C7D-...)]PowerToysExtension.cs与清单中的Class Id一一对应——这正是注册身份与进程内实现通过 GUID 耦合的源码证据。本地开发循环五个步骤官方文档powertoys-extension-local-development.md给出的标准循环如下下面结合仓库实现逐条展开。步骤 1构建 PackageIdentity产出稀疏 MSIX构建 PackageIdentity.vcxproj。它本质是一个Utility类型的 C 项目真正的逻辑在 BuildSparsePackage.ps1vcxproj 在PrepareForBuild之前以pwsh -File BuildSparsePackage.ps1 -Platform ... -Configuration ...调用它见 PackageIdentity.vcxproj。脚本按如下步骤产出PowerToysSparse.msix在src/PackageIdentity/.user\下准备开发证书见下文信任开发证书读取src/Version.props获取版本号并把版本写回临时的清单副本BuildSparsePackage.ps1用 Windows SDK 的makeappx.exe把仅清单 Images 资产打成一个不含 payload 的稀疏 MSIX本地构建还会把发布者改写为开发证书主体CNPowerToys Dev, ...见 BuildSparsePackage.ps1用signtool.exe以开发证书指纹签名CI 可用-NoSign跳过见 BuildSparsePackage.ps1。产出位置$(仓库根)/Platform/Configuration/PowerToysSparse.msix例如x64\Debug\PowerToysSparse.msix。构建日志末尾会直接打印下一步要执行的Add-AppxPackage命令BuildSparsePackage.ps1。提示也可以绕过 vcxproj 直接运行 BuildSparsePackage.ps1脚本支持-Platformx64/arm64、-ConfigurationDebug/Release、-Clean、-ForceCert、-NoSign、-CIBuild、-DevRegister、-Unregister等参数见脚本开头 [Param] 块。其中-DevRegister会自动完成信任证书 注册稀疏包两件事适合一键开发注册。步骤 2信任开发证书Add-AppxPackage只接受受信任签名者的包。构建脚本会自动生成或复用开发证书src/PackageIdentity/.user/PowerToysSparse.certificate.sample.cer并把其私钥保存在Cert:\CurrentUser\My证书主体CNPowerToys Dev, OPowerToys, LRedmond, SWashington, CUS有效期 12 个月见 [BuildSparsePackage.ps1](https://link.gitcode.com/i/023c55ae56ec7ec9e11615a634b2ddfc#L50-L56, L193-L232)。将其导入CurrentUser\TrustedPeople$repoRoot C:/git/PowerToys Import-Certificate -FilePath $repoRoot/src/PackageIdentity/.user/PowerToysSparse.certificate.sample.cer -CertStoreLocation Cert:\CurrentUser\TrustedPeople若 Windows 仍报告信任失败典型错误码0x800B0109即证书链不受信把同一证书也导入Cert:\CurrentUser\TrustedRoot。这也是脚本-DevRegister分支默认同时导入两个存储的原因BuildSparsePackage.ps1。步骤 3注册稀疏包执行构建输出里打印的Add-AppxPackage命令。它的形态是Add-AppxPackage -Path repo\Platform\Configuration\PowerToysSparse.msix -ExternalLocation repo\Platform\Configuration\WinUI3Apps-Path指向刚生成的稀疏 MSIX-ExternalLocation指向同一输出根下的WinUI3Apps\目录——这就是扩展 exe 所在目录稀疏包的外部内容都从这里按清单相对路径解析清单里同时有uap10:AllowExternalContenttrue/uap10:AllowExternalContent见 AppxManifest.xml。注册成功后系统内出现包Microsoft.PowerToys.SparseApp且具备runFullTrust、internetClient、systemAIModels等能力见 AppxManifest.xml为其中的 full-trust exe 提供稳定的包家族名Package Family Name。步骤 4以相同平台与配置构建扩展本体构建 Microsoft.CmdPal.Ext.PowerToys.csproj。关键点项目把OutputPath直接指向输出根下的WinUI3Apps\子目录$(RepoRoot)$(Platform)\$(Configuration)\WinUI3Apps\csproj例如x64\Debug\WinUI3Apps或ARM64\Debug\WinUI3Apps——与清单ExecutableMicrosoft.CmdPal.Ext.PowerToys.exe相对ExternalLocation的解析位置精确对应未显式传RuntimeIdentifier时按平台自动选择win-x64或win-arm64csproj项目以自包含 AOT 发布方式产出原生代码SelfContained/PublishAot/PublishTrimmed均为 true见 csproj它引用了一系列模块服务与公共库包括Awake.ModuleServices、colorPicker/ColorPicker.ModuleServices、FancyZonesEditorCommon、Workspaces.ModuleServices、ManagedCommon、Common.Search、Common.UI与Microsoft.CommandPalette.Extensions.Toolkit见 csproj因此这些模块的改动也可能需要一并重新编译。构建完成后检查x64\Debug\WinUI3Apps\Microsoft.CmdPal.Ext.PowerToys.exe是否已更新。步骤 5重启 Command Palette关闭所有正在运行的 CmdPal 实例后重新启动。CmdPal 在启动时重新枚举已注册的 app extensioncom.microsoft.commandpalette激活并加载新的扩展进程-RegisterProcessAsComServer模式。若扩展未重新加载优先排查是否残留了旧的 CmdPal / 扩展进程或确认步骤 4 的产物确实覆盖了WinUI3Apps下的 exe。何时需要重做哪些步骤官方文档给出了精简的取舍原则展开如下改动类型需要执行的步骤原因源码依据普通 C# 代码改动如新增某个模块命令、修改命令逻辑仅步骤 4 步骤 5清单不变、证书不变、身份不变只需更新WinUI3Apps下的 exe 并让 CmdPal 重载稀疏包清单变化如新增Application、改 Class Id、改 Capabilities步骤 1 → 3 → 4 → 5清单内容在打包时才固化进 msix注册信息以注册时的清单为准签名证书变化证书过期、被删除、-ForceCert重建步骤 1 → 2 → 3 → 4 → 5新证书的 Thumbprint/发布者不同必须重新签名并重新信任注册时的发布者需与清单一致切换输出根如x64\Debug↔ARM64\Debug步骤 1 → 3 → 4 → 5-ExternalLocation指向的是绝对输出路径换目录意味着上一次注册失效需重新注册只想清理注册不再需要该稀疏包运行pwsh -File src/PackageIdentity/BuildSparsePackage.ps1 -Unregister脚本-Unregister分支会移除Microsoft.PowerToys.SparseAppBuildSparsePackage.ps1普通代码改动时重建PackageIdentity并非必须——稀疏包只是身份的外壳内容没变就不必重打、重签、重注册这能显著缩短每次迭代的周期。常见问题与排障线索Add-AppxPackage报0x800B0109证书链不受信开发证书尚未进入受信任存储。按步骤 2 同时导入TrustedPeople与TrustedRoot后重试。注册成功但 CmdPal 里看不到 PowerToys 命令确认扩展 exe 是否存在于-ExternalLocation指向的WinUI3Apps\目录且与稀疏包同平台同配置确认 CmdPal 已完全退出后重启。改了代码但行为没变化检查 csproj 是否把输出写到了同一个输出根路径拼接来自$(RepoRoot)$(Platform)\$(Configuration)平台不一致时会落到另一个目录必要时在扩展进程内查看日志。扩展本身把运行时日志写到\CmdPal\PowerToysExtension\Logs见 Program.cs启动参数、进程架构等信息都会记录在该目录下是排查加载失败的第一手资料。小结PowerToys 的命令面板扩展采用稀疏包提供身份 ExternalLocation 外部内容 WinUI3Apps 输出目录三层结构把 MSIX 身份管理与实际二进制迭代解耦。日常开发只需遵循重编译扩展 → 重启 CmdPal的快速循环只有触及清单、证书或切换输出根时才需要重走重建 PackageIdentity → 信任证书 →Add-AppxPackage注册的完整链路。相关脚本 BuildSparsePackage.ps1 与清单 AppxManifest.xml 是理解这套机制的最佳入口。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考