Winui packaging

Skill microsoft/win-dev-skills/plugins/winui/skills/winui-packaging

Agents and skills for building Windows apps with WinUI 3 and the Windows App SDK

Install

npx -y skills add microsoft/win-dev-skills --skill winui-packaging

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its author says it does

Copied from the file, not written here

MSIX packaging, code signing, and distribution for WinUI 3 apps — build for release, certificate generation (winapp cert generate), certificate trust, code signing (winapp sign), self-contained deployment, CI/CD with GitHub Actions, and Microsoft Store submission. Use when preparing for release, creating MSIX installers, managing certificates, setting up CI/CD packaging, or publishing to the Microsoft Store.

SKILL.md

4.8 KB, as published. Nobody here has run it

Quick Reference

Task	Command
Build for release	`.\BuildAndRun.ps1 /p:Configuration=Release`
Package + sign	`winapp package <dir> --cert devcert.pfx`
Generate + sign + package	`winapp package <dir> --generate-cert --install-cert`
Generate dev certificate	`winapp cert generate`
Trust certificate (admin)	`winapp cert install ./devcert.pfx`
Sign existing file	`winapp sign ./app.msix ./devcert.pfx`
Self-contained deployment	`winapp package <dir> --cert devcert.pfx --self-contained`

End-to-End Workflow

Step 1: Build for Release

Use the BuildAndRun.ps1 script from the winui-dev-workflow skill to build your app in Release configuration without launching it:

.\BuildAndRun.ps1 /p:Configuration=Release -SkipRun

Step 2: Generate Certificate (one-time)

winapp cert generate --manifest .

Creates devcert.pfx (default password: password). The --manifest flag auto-matches the Publisher field in Package.appxmanifest.

Step 3: Trust Certificate (one-time, requires admin)

winapp cert install ./devcert.pfx

Adds cert to machine Trusted Root store. Persists across reboots.

Step 4: Package and Sign

winapp package <build-output-dir> --cert ./devcert.pfx

This locates appxmanifest.xml, stages the layout, generates resources.pri, creates .msix, and signs it.

Step 5: Install or Distribute

# Local install
Add-AppxPackage ./MyApp.msix

# Or double-click the .msix file

Key Rules

Publisher must match between certificate and manifest Identity.Publisher — use winapp cert generate --manifest to auto-match
Prefer winapp package --cert over separate winapp sign — one step instead of two
cert install requires admin — run terminal as Administrator
Default PFX password is password — override with --password
--timestamp is critical for production — without it, signatures expire with the cert:
```
winapp package <dir> --cert prod.pfx --timestamp http://timestamp.digicert.com
```
--self-contained bundles Windows App SDK runtime — larger but no runtime dependency

CI/CD with GitHub Actions

name: Build and Package
on: [push]
jobs:
  build:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - uses: microsoft/[email protected]

      - name: Build
        run: dotnet build -c Release -p:Platform=x64

      - name: Package
        run: |
          winapp cert generate --if-exists skip --quiet
          winapp package ./bin/x64/Release/ --cert ./devcert.pfx --quiet

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: msix-package
          path: "*.msix"

CI/CD tips:

Use --quiet for clean output
Use --if-exists skip with cert generate to avoid failures on re-runs
Store production PFX as a repository secret

Store Submission

Partner Center account — register at partner.microsoft.com
Age ratings — complete the questionnaire in Partner Center
Screenshots — capture at 1366x768 minimum resolution
Privacy policy — required for apps that access internet or user data
Submit: upload the signed .msix / .msixbundle produced by winapp package via Microsoft Partner Center — Apps and games → your app → Packages. Microsoft Store submission is browser-based; there is no first-party CLI submit command yet.

Troubleshooting

Error	Solution
"Publisher mismatch"	Run `winapp cert generate --manifest` to re-generate
"Certificate not trusted"	Run `winapp cert install ./devcert.pfx` as admin
"Access denied"	`cert install` needs admin elevation
"Certificate file already exists"	Use `--if-exists overwrite` or `--if-exists skip`
"appxmanifest.xml not found"	Run `winapp init` or pass `--manifest <path>`
"Package installation failed"	Trust cert first; remove stale: `Get-AppxPackage <name> \| Remove-AppxPackage`
Signature invalid after time	Re-sign with `--timestamp`

References

File	Read when...
`references/sourcegen-patterns.md`	Setting up AOT/trimming, JSON source generators, NativeAOT readiness, CsWin32