--- 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:

```powershell .\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) ```powershell 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) ```powershell winapp cert install ./devcert.pfx ``` Adds cert to machine Trusted Root store. Persists across reboots.

#### Step 4: Package and Sign ```powershell 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 ```powershell # 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 <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

```yaml 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 |

--- 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:

```powershell .\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) ```powershell 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) ```powershell winapp cert install ./devcert.pfx ``` Adds cert to machine Trusted Root store. Persists across reboots.

#### Step 4: Package and Sign ```powershell 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 ```powershell # 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 <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

```yaml 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 |

--- 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:

```powershell .\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) ```powershell 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) ```powershell winapp cert install ./devcert.pfx ``` Adds cert to machine Trusted Root store. Persists across reboots.

#### Step 4: Package and Sign ```powershell 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 ```powershell # 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 <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

```yaml 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 |

--- 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:

```powershell .\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) ```powershell 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) ```powershell winapp cert install ./devcert.pfx ``` Adds cert to machine Trusted Root store. Persists across reboots.

#### Step 4: Package and Sign ```powershell 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 ```powershell # 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 <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

```yaml 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 |