Deployment Models

Deployment has two separate axes:

Packaging: packaged MSIX, packaged with external location, or unpackaged.
Runtime: framework-dependent or self-contained.

flowchart TD
    start(["Choose distribution"]) --> store{"Microsoft Store target?"}
    store -->|Yes| packaged["Packaged MSIX"]
    store -->|No| existing{"Existing installer must stay?"}
    existing -->|Yes| external["Package with external location"]
    existing -->|No| internal{"Internal or xcopy tool?"}
    internal -->|Yes| unpackaged["Unpackaged"]
    internal -->|No| packaged
    packaged --> fd["Usually framework-dependent"]
    external --> runtime["Bootstrap or deploy runtime"]
    unpackaged --> selfcontained["Prefer self-contained for direct/xcopy"]

Packaging Axis

Model	Use when	Costs
Packaged MSIX	New WinUI app, Store path, package identity features	MSIX/package tooling and manifest discipline
Packaged with external location	Existing installer must stay but package identity is needed	More moving parts: sparse identity plus existing installer
Unpackaged	Internal tools or environments where MSIX is blocked	You own runtime, updates, identity alternatives, signing, SmartScreen

Runtime Axis

Model	Use when	Costs
Framework-dependent	Store/MSIX or controlled environments can install runtime dependencies	Target machine must have the right Windows App Runtime packages
Self-contained	Direct download, xcopy, CI artifact, or machines where runtime install is friction	Larger output; some APIs still depend on additional packages/services

Package Identity Features

Package identity matters for features such as notifications, startup tasks, file/protocol associations, share targets, app services, and other Windows extensibility points.

If a feature depends on package identity, do not prototype it as unpackaged without a fallback plan.

Gotcha: PublishSingleFile is only for unpackaged self-contained WinUI 3 apps in supported Windows App SDK versions. Packaged apps do not support single-file output.