From a953a39aec63fed39295f2012e83427af4b709ff Mon Sep 17 00:00:00 2001 From: Kai Tao <69313318+vanzue@users.noreply.github.com> Date: Sat, 7 Mar 2026 19:08:53 +0800 Subject: [PATCH] Chore: PowerToys extension development dev guide, and clean an unused msix declaration (#45967) ## Summary of the Pull Request PowerToys extension development dev guide, and clean an unused msix declaration ## PR Checklist - [ ] Closes: #xxx - [ ] **Communication:** I've discussed this with core contributors already. If the work hasn't been agreed, this work might be rejected - [ ] **Tests:** Added/updated and all pass - [ ] **Localization:** All end-user-facing strings can be localized - [ ] **Dev docs:** Added/updated - [ ] **New binaries:** Added on the required places - [ ] [JSON for signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json) for new binaries - [ ] [WXS for installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs) for new binaries and localization folder - [ ] [YML for CI pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml) for new test projects - [ ] [YML for signed pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml) - [ ] **Documentation updated:** If checked, please file a pull request on [our docs repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys) and link it here: #xxx ## Detailed Description of the Pull Request / Additional comments ## Validation Steps Performed --- .../powertoys-extension-local-development.md | 47 +++++++++++++++++++ .../app.manifest | 6 --- 2 files changed, 47 insertions(+), 6 deletions(-) create mode 100644 src/modules/cmdpal/doc/powertoys-extension-local-development.md diff --git a/src/modules/cmdpal/doc/powertoys-extension-local-development.md b/src/modules/cmdpal/doc/powertoys-extension-local-development.md new file mode 100644 index 0000000000..506adfb61e --- /dev/null +++ b/src/modules/cmdpal/doc/powertoys-extension-local-development.md @@ -0,0 +1,47 @@ +# Local PowerToys Extension Development + +This guide is for iterating on `src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.PowerToys/Microsoft.CmdPal.Ext.PowerToys.csproj`. + +The extension is registered through the shared sparse package defined in `src/PackageIdentity/AppxManifest.xml`. That manifest declares `Microsoft.CmdPal.Ext.PowerToys.exe` at the sparse package root, so the sparse package and the extension must be built for the same platform and configuration, for example `x64\Debug`. + +## Local development loop + +1. Build `src/PackageIdentity/PackageIdentity.vcxproj`. + + This creates `PowerToysSparse.msix` in the repo output root for the selected platform and configuration, and prints the `Add-AppxPackage` command you should run next. + +2. Trust the development certificate before running `Add-AppxPackage`. + + The `PackageIdentity` build creates or reuses `src/PackageIdentity/.user/PowerToysSparse.certificate.sample.cer`. + + Import it into `CurrentUser\TrustedPeople`: + + ```powershell + $repoRoot = "C:/git/PowerToys" + Import-Certificate -FilePath "$repoRoot/src/PackageIdentity/.user/PowerToysSparse.certificate.sample.cer" -CertStoreLocation Cert:\CurrentUser\TrustedPeople + ``` + + If Windows still reports a trust failure such as `0x800B0109`, also import the same certificate into `Cert:\CurrentUser\TrustedRoot`. + +3. Run the `Add-AppxPackage` command printed by the `PackageIdentity` build. + + That registers `Microsoft.PowerToys.SparseApp` as a sparse package and points it at the matching output root through `-ExternalLocation`. + + The command will look like this: + + ```powershell + Add-AppxPackage -Path "\\\PowerToysSparse.msix" -ExternalLocation "\\" + ``` + +4. Build `src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.PowerToys/Microsoft.CmdPal.Ext.PowerToys.csproj` in the same platform and configuration. + + This project writes `Microsoft.CmdPal.Ext.PowerToys.exe` directly into the sparse package root, such as `x64\Debug` or `ARM64\Debug`. That matches the `Executable="Microsoft.CmdPal.Ext.PowerToys.exe"` entry in `src/PackageIdentity/AppxManifest.xml`. + +5. Restart Command Palette. + + Close any running CmdPal instance and launch it again so it reloads app extensions and picks up the rebuilt `Microsoft.CmdPal.Ext.PowerToys` binaries. + +## When to repeat each step + +- Rebuild and re-register `PackageIdentity` when the sparse package manifest changes, the signing certificate changes, or you switch to a different output root such as `ARM64\Debug`. +- For normal code changes in `Microsoft.CmdPal.Ext.PowerToys`, rebuilding the extension project and restarting CmdPal is enough. diff --git a/src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.PowerToys/app.manifest b/src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.PowerToys/app.manifest index 013aaee199..5b42025bfd 100644 --- a/src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.PowerToys/app.manifest +++ b/src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.PowerToys/app.manifest @@ -1,11 +1,5 @@ - - - PerMonitorV2