/winui-packaging

name: winui-packaging
description: "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."

Quick Reference

| Task | Command | |------|---------| | Build for release | `.\BuildAndRun.ps1 . -c Release --arch x64 --no-launch` | | 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

Build the project in Release configuration without launching it. Use the `BuildAndRun.ps1` wrapper from the `winui-dev-workflow` skill — plain `dotnet build` does **not** load the bundled `Microsoft.WindowsAppSDK.Analyzers`, so release builds would ship without the analyzer gate that development builds get:

.\BuildAndRun.ps1 . -c Release --arch x64 --no-launch

`--no-launch` builds and registers a development package without starting the app. Run `winapp unregister` before installing the signed `.msix` in Step 5, so the development registration does not conflict with the packaged identity.

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/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 plain `dotnet build` on the runner, not `BuildAndRun.ps1` — the wrapper registers a development package and needs the plugin's local analyzer payload, neither of which belongs in CI. Enforce analyzer coverage on the dev machine instead.
• 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](https://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](https://partner.microsoft.com/dashboard) — 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 |