winui-packaging

Scope: WinUI 3 apps only. The Windows App SDK is not WinUI. A WPF, WinForms, Electron, or other app that references the Windows App SDK (for notifications, packaging, or other APIs) is not a WinUI app; keep its framework and don't apply this skill unless the task is to port it to WinUI 3. A WinUI 3 project has <UseWinUI>true</UseWinUI> or uses Microsoft.UI.Xaml.

Requires WinApp CLI 0.7+. For analyzer setup, see winui-dev-workflow.

Quick Reference

End-to-End Workflow

Step 1: Check the Project and Deployment Intent

• Pass the explicit project file, not . or a guessed bin folder. WinUI project packaging uses SDK-native dotnet publish packaging, defaults to Release, and preserves project AOT settings.
• Check manifest identity, target architectures, the SDK for the app's TFM, and release warnings.
• For Native AOT, set <PublishAot>true</PublishAot> in the project and fix IL/CsWinRT warnings; there is no `winapp package --aot`. AOT also needs the MSVC C++ build tools. See source-generator patterns.
• Project packaging rejects WindowsPackageType=None; restore the packaged setting first (see winui-dev-workflow Critical Rules).

Do not run/register/unregister a development package just to produce release artifacts. Project packaging builds without a development winapp run --no-launch step. For WinUI SDK-native packaging, do not pass layout overrides --manifest, --executable, or --skip-pri; fix the project/manifest instead.

Step 2: Generate Certificate (one-time)

winapp cert generate --manifest .\Package.appxmanifest

Creates a development devcert.pfx (default password: password). This certificate command's --manifest flag auto-matches the Publisher field in Package.appxmanifest. Keep PFX files/passwords out of source control; production signing needs the organization's signing policy.

Step 3: Trust on the Intended Test Machine (optional, admin)

winapp cert install ./devcert.pfx

Adds the cert to the machine trust store and persists across reboots. Do this only with approval on the intended test machine; it is not required just to build/package in CI.

Step 4: Package and Sign

winapp package .\MyApp.csproj --arch x64 --cert .\devcert.pfx
# Repeat --arch for a bundle
winapp package .\MyApp.csproj --arch x64 --arch arm64 --no-sign

Choose one signing policy: --cert takes a PFX file, not a certificate thumbprint; its subject must match the manifest's Identity.Publisher. --no-sign leaves an artifact for external signing. Use the artifact paths reported by the command, not a guessed output directory.

For timestamped production signing, create an unsigned package then sign the resulting artifact:

# Replace MyApp.msix with the package/bundle path returned above
winapp sign .\MyApp.msix .\prod.pfx --timestamp http://timestamp.digicert.com

--timestamp belongs to `winapp sign`, not winapp package. Use an approved timestamp service and protect the PFX/password.

Step 5: Install or Distribute

When installation/testing is part of the task, choose the target per winui-ui-testing Step 1, and get consent for certificate trust and dependency provisioning on that machine. Packaging alone is not permission to install an app.

Self-Contained Does Not Mean Single-File

winapp package --self-contained sets only `WindowsAppSDKSelfContained=true`, not .NET SelfContained=true. For a fully self-contained JIT .NET app, set both in the project:

<PropertyGroup>
  <SelfContained>true</SelfContained>
  <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
</PropertyGroup>

Native AOT covers the .NET runtime but still needs the Windows App SDK choice. Native WinUI runtime files stay alongside the executable/in the package; do not promise a single-file WinUI EXE. Some APIs still require additional MSIX dependencies; see the deployment guidance.

CI/CD

On a Windows runner provisioned with CLI 0.7+, the app's .NET SDK, and (for AOT) the native C++ toolchain, the packaging step can be:

winapp package .\MyApp.csproj --arch x64 --arch arm64 --no-sign

• Committed package references, including the analyzer, restore normally; no machine-local analyzer is needed.
• Archive the reported .msix/.msixbundle outputs using the CI system's artifact step. No UI launch or development registration is needed.
• Retrieve production signing material through approved secret storage and sign in a separate protected step. Never commit a PFX or install a development root certificate just to build.

Store Submission

Associate the app with its Partner Center identity and follow its current submission requirements (package validation, ratings, screenshots, privacy policy). Use the SDK/Visual Studio packaging workflow when Store-upload artifacts or resource-package splitting are required. winapp package produces package artifacts; it does not publish to the Store or replace that submission workflow.

Troubleshooting

References