Skip to content

Commit ed1e99c

Browse files
GrantMeStrengthGrantMeStrength
authored
Merge pull request #6489 from MicrosoftDocs/fix/choose-packaging-model
Add 'Choose a packaging model' decision guide
2 parents 97aff04 + 580efa3 commit ed1e99c

3 files changed

Lines changed: 131 additions & 0 deletions

File tree

‎hub/apps/package-and-deploy/choose-packaging-model.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
title: Choose a packaging model for your Windows app
3+
description: Decide whether your Windows app should be packaged (MSIX), unpackaged, or use package identity with external location—based on your distribution scenario and feature requirements.
4+
ms.topic: concept-article
5+
ms.date: 03/19/2026
6+
keywords: packaged, unpackaged, MSIX, package identity, sparse package, external location, Windows App SDK, WinUI, distribution
7+
ms.localizationpriority: medium
8+
---
9+
10+
# Choose a packaging model for your Windows app
11+
12+
> [!NOTE]
13+
> **Building a new WinUI 3 app?** You're already packaged by default. This page is for developers who need to make an explicit choice—typically when porting an existing app, deploying to enterprise machines, or adding Windows features to an app that wasn't originally packaged.
14+
15+
Windows apps can be packaged, unpackaged, or somewhere in between. The right choice depends on two things: **how you're distributing your app** and **which Windows features you need**.
16+
17+
## Start with your scenario
18+
19+
### "I'm an indie developer publishing to the Microsoft Store"
20+
21+
**Use a packaged MSIX app.** The Store requires MSIX packaging. WinUI 3 apps created in Visual Studio are packaged by default—you don't need to make any changes. You get clean installation, automatic updates, and access to all package-identity-gated features like notifications and background tasks.
22+
23+
→ [Distribute your packaged app](../desktop/modernize/desktop-to-uwp-distribute.md)
24+
25+
---
26+
27+
### "I'm building an enterprise app deployed via Intune or Configuration Manager"
28+
29+
**Start packaged; consider external location if you have an existing installer.**
30+
31+
- If you're building a new app, use MSIX. It integrates cleanly with Intune and SCCM/ConfigMgr and gives you full package identity.
32+
- If you have an **existing app with its own installer** that you can't replace, use [packaging with external location](#packaging-with-external-location). This gives your app package identity—and access to features like notifications and background tasks—without changing how or where you deploy.
33+
- If your app genuinely needs no Windows-identity-gated features and you control the deployment environment, unpackaged works, but you'll hit a wall the first time you try to add notifications or AI features.
34+
35+
→ [Deploy packaged apps (Windows App SDK)](../windows-app-sdk/deploy-packaged-apps.md)
36+
→ [Grant package identity by packaging with external location](../desktop/modernize/grant-identity-to-nonpackaged-apps-overview.md)
37+
38+
---
39+
40+
### "I'm an ISV shipping a direct download with my own installer"
41+
42+
**Use packaging with external location (formerly called sparse packages).**
43+
44+
This is the sweet spot for existing Win32/WPF/WinForms apps that ship via their own installer (NSIS, WiX, InstallShield, etc.) and don't want to replace it with MSIX. You register a lightweight identity package alongside your existing installer, your binaries stay where they are, and you unlock the full set of package-identity-gated Windows features.
45+
46+
Your users won't see any change in how they install or update your app. You get the Windows features; they get a familiar experience.
47+
48+
→ [Grant package identity by packaging with external location](../desktop/modernize/grant-identity-to-nonpackaged-apps-overview.md)
49+
→ [Add an identity package in Visual Studio](../desktop/modernize/grant-identity-to-nonpackaged-apps-visual-studio.md)
50+
51+
---
52+
53+
### "I'm building an internal tool or developer utility"
54+
55+
**Unpackaged is fine—with caveats.**
56+
57+
Unpackaged apps are the simplest to build and deploy: xcopy, robocopy, or a simple script is all you need. The Windows App SDK works in unpackaged apps via NuGet. But some features won't be available, and if you later decide you need them, retrofitting package identity is non-trivial.
58+
59+
Before you commit to unpackaged, check the [features table below](#features-that-require-package-identity) against your roadmap. If notifications, background tasks, or AI APIs are on the horizon, consider starting packaged.
60+
61+
---
62+
63+
## Packaging models at a glance
64+
65+
| Model | Package identity | Installer | Store eligible | Best for |
66+
|---|---|---|---|---|
67+
| **Packaged (MSIX)** | ✅ Yes | MSIX replaces installer | ✅ Yes | New apps, Store publishing, enterprise MDM |
68+
| **Packaging with external location** | ✅ Yes | Your existing installer | ❌ No | Existing apps with own installer, ISVs |
69+
| **Unpackaged** | ❌ No | XCopy / script | ❌ No | Internal tools, dev utilities, simple scenarios |
70+
71+
## Features that require package identity
72+
73+
These Windows features only work in apps that have package identity—either through full MSIX packaging or [packaging with external location](#packaging-with-external-location).
74+
75+
| Feature | Notes |
76+
|---|---|
77+
| **App notifications (toast)** | `AppNotificationManager` requires package identity |
78+
| **Background tasks** | Registration requires package identity |
79+
| **Windows AI APIs** (Phi Silica, OCR, etc.) | Most Windows AI APIs require package identity |
80+
| **Push notifications** (WNS) | Channel registration requires package identity |
81+
| **Share target** | Declared in package manifest |
82+
| **Custom context menu extensions** | Declared in package manifest |
83+
| **File type and protocol associations** | Rich associations require package identity |
84+
| **Startup tasks** | Requires package identity |
85+
| **App services** | Requires package identity |
86+
87+
> [!TIP]
88+
> If you're unpackaged and hitting `E_ILLEGAL_METHOD_CALL` or `APPMODEL_ERROR_NO_PACKAGE` errors when calling Windows APIs, that's the package identity requirement. See [packaging with external location](#packaging-with-external-location) as the lowest-friction fix.
89+
90+
## Packaging with external location
91+
92+
Packaging with external location (also called *sparse packages*) lets you register a small identity package alongside your existing app—without changing your installer, binary locations, or update process. It was introduced in Windows 10 version 2004 (build 19041).
93+
94+
You provide:
95+
- A package manifest (XML file describing your app identity)
96+
- A signed `.msix` containing only the manifest (no binaries)
97+
98+
Your existing installer registers this identity package, and Windows treats your app as having package identity from that point on.
99+
100+
This is distinct from full MSIX packaging:
101+
102+
| | MSIX | External location |
103+
|---|---|---|
104+
| Replaces your installer | Yes | No |
105+
| Binaries inside the package | Yes | No (external) |
106+
| Store eligible | Yes | No |
107+
| Package identity | Yes | Yes |
108+
| Update mechanism | MSIX update | Your existing mechanism |
109+
110+
→ [Full walkthrough: Grant package identity by packaging with external location](../desktop/modernize/grant-identity-to-nonpackaged-apps-overview.md)
111+
112+
## Framework-dependent vs self-contained deployment
113+
114+
Separately from packaging model, apps using the Windows App SDK choose how to carry their runtime dependencies:
115+
116+
- **Framework-dependent**: The Windows App SDK runtime must be installed on the user's machine. Smaller app footprint; relies on the runtime being present or auto-installed.
117+
- **Self-contained**: All Windows App SDK binaries ship with your app. Larger footprint; no external runtime requirement. Good for locked-down enterprise environments.
118+
119+
→ [Deploy self-contained apps](self-contained-deploy/deploy-self-contained-apps.md)
120+
121+
## Related content
122+
123+
- [Features that require package identity](../desktop/modernize/modernize-packaged-apps.md)
124+
- [Package identity overview](../desktop/modernize/package-identity-overview.md)
125+
- [Deploy packaged apps (Windows App SDK)](../windows-app-sdk/deploy-packaged-apps.md)
126+
- [Deploy unpackaged apps (Windows App SDK)](../windows-app-sdk/deploy-unpackaged-apps.md)
127+
- [Tutorial: Unpackage a WinUI app](unpackage-winui-app.md)

‎hub/apps/package-and-deploy/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ ms.localizationpriority: medium
1414

1515
App packaging provides your application with a predictable installation, update, and servicing model on Windows. While WinUI 3 apps are packaged by default, many other types of apps aren't. And adding package identity unlocks a wide range of Windows capabilities. Features that depend on package identity to function include background tasks, notifications, live tiles, custom context menu extensions, share targets, and other extensibility points. Packaging also helps ensure cleaner deployments, reliable updates, and streamlined distribution through channels such as the Microsoft Store and enterprise deployment tools.
1616

17+
Not sure which packaging model is right for your app? See [Choose a packaging model](choose-packaging-model.md).
18+
1719
When deploying apps that use the Windows App SDK, you can choose between framework-dependent and self-contained deployment models. Framework-dependent apps rely on the Windows App SDK runtime and/or framework package being installed on the user’s machine. In contrast, self-contained apps bundle the Windows App SDK dependencies directly with the application, ensuring the app carries everything it needs to run. The right model depends on your distribution scenario, update strategy, and how much control you want over the app’s footprint and dependencies.
1820

1921
---

‎hub/apps/package-and-deploy/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@ items:
33
href: ../desktop/index.yml
44
- name: Package and deploy overview
55
href: ../package-and-deploy/index.md
6+
- name: Choose a packaging model
7+
href: ../package-and-deploy/choose-packaging-model.md
68
- name: Packaging
79
items:
810
- name: Overview

0 commit comments

Comments
 (0)