Winui Packaging

Quick Reference

| Task | Command | |------|---------| | Build for release | .\BuildAndRun.ps1 /p:Configuration=Release | | Package + sign | winapp package --cert devcert.pfx | | Generate + sign + package | winapp package --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 --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  --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:

``powershell winapp package --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/setup-WinAppCli@v0.1

      - 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

1. Partner Center account — register at partner.microsoft.com
2. Age ratings — complete the questionnaire in Partner Center
3. Screenshots — capture at 1366x768 minimum resolution
4. Privacy policy — required for apps that access internet or user data
5. 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 | | "Package installation failed" | Trust cert first; remove stale: Get-AppxPackage \| 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 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: microsoft
• Source: microsoft/win-dev-skills
• License: MIT

Install and usage instructions live in the source repository linked above.