Skip to content

Add API support matrix for packaging configurations #6236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
guimafelipe wants to merge 1 commit into from
Closed

Add API support matrix for packaging configurations #6236

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
143 changes: 143 additions & 0 deletions docs/api-support-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,143 @@
# Windows App SDK API Support Matrix

This document provides a centralized reference showing which Windows App SDK APIs
are supported under each packaging and configuration combination.
Copy link
Copy Markdown
Member

@DrusTheAxe DrusTheAxe Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is problematic and increasingly so over time.

For one, only a fraction of feature areas are mentioned. I see nothing about Decimal, Dynamic Dependencies, Environment Manager, OAuth, Package Management, Runtime Compatibility or more.

For another, the level of detail is partial and asymmetric. For example, the Application Data table lists 2 of the 4 static methods and none of the instance methods. Nor is there any relation to apicontract version - 1 of the static methods mentioned is v2, the other and the others not mentioned are v1.

Furthermore, the standard is all Windows App SDK APIs are required to work on all supported platforms and in support supported configurations, unless exceptional justifications apply.

If you're seeking to ensure clear documentation of what is and isn't available, across all platforms and configurations, you'd be better off refocusing this document on the exceptions. That's a much smaller, tractable and maintainable list, and provides more value to the reader (just the exceptions, not cluttered with the far more numerous 'normal'/everywhere cases).

For example:

Overview

This document applies to all releases of Windows App SDK version 2.* .

Packaged vs Unpackaged

Windows App SDK's runtime can be used by packaged and unpackaged processes except where otherwise stated. See Package vs unpackaged apps for more information about packaged vs unpackaged.

Configurations

Windows App SDK's runtime can be used via MSIX packages or Self-Contained unless stated otherwise.

These configurations are referred to as WinAppSDK/MSIX and WinAppSDK/SelfContained.

Platform Support

Windows App SDK supports the following platforms unless stated otherwise:

  • Windows Desktop version >= 10.0.17763.0 (aka RS5)
  • Windows Server version >= 10.0.something.0 (aka 2019)

Exceptions

Bar

The Bar feature is only available on Windows Desktop version >= 10.0.12345.678.

Foo

The Foo feature's API Microsoft.Windows.Huh.Foo.HowAboutNow() does not support WinAppSDK/MSIX for Unpackaged processes.

The Foo feature is only available on Windows Desktop version >= 10.0.23456.87 and Windows Server version >= 2025 (10.0.34567.0).

Meh

The Meh feature does not support WindowsAppSDK/SelfContained.

The Meh feature 's API `Microsoft.Windows.Yawn.Meh.JustDoIt() is only available on Windows Server >= 2025 (10.0.34567.0).


## Legend

| Symbol | Meaning |
|--------|---------|
| Y | Fully supported |
| N | Not supported |
| P | Partial support (see Notes) |
Copy link
Copy Markdown
Member

@DrusTheAxe DrusTheAxe Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

SUGGESTION: Change 'P' to as a reference to a footnote after the table e.g.

| API | Packaged | Unpackaged | Self-Contained | Notes |
...
| PushNotificationManager.Unregister() | Y | Y | 1 | |

  1. Image protocols in notifications only support file:// URIs in Unpackaged and Self-Contained configurations.


## Packaging and Configuration Combinations

| Combination | Description |
Copy link
Copy Markdown
Member

@DrusTheAxe DrusTheAxe Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Combination heading should be Configuration

|-------------|-------------|
| **Packaged (MSIX)** | App deployed via MSIX Desktop Bridge with full package identity |
Copy link
Copy Markdown
Member

@DrusTheAxe DrusTheAxe Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Packaged

Remove the (MSIX).

Copy link
Copy Markdown
Member

@DrusTheAxe DrusTheAxe Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm puzzled over this whole table.

Rows 1+2 are orthogonal to 3+4.

Let's start with the 1st row, **Packaged (MSIX)". Ignoring the "(MSIX)" part is redundant and misleading, the description for the phrase "Packaged" is incorrect and misleading.

  • "Packaged" means "process HAS package identity"
  • "Unpackaged" means "process LACKS package identity"

https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/packaging/#packaged-vs-unpackaged-apps

There are many ways you can distribute and install and ultimately get a running process with package identity.

Additionally, "MSIX Desktop Bridge" aka "Desktop Bridge" aka "packagedClassicApp" aka "Centennial app" isn't the only form of a running process with package identity. If you specify uap10:RuntimeBehavior="win32App" in appxmanifest.xml you get a "Win32app" aka "Win32alacarte" running process which has package identity. Such processes are not Desktop Bridge processes but no less Packaged processes, as they equally have package identity.

For another example, a packaged Service, specified via desktop6:Service in appxmanifest.xml also produces a running process with package identity and is equally a "Packaged" process, despite no Desktop Bridge in play.

There's also Packaged processes you get by running some non-MSIX installer to install classic unpackaged software and registered a package with a External Location pointing to that classic unpackaged software so when c:\classic\non-msix\installed\foo.exe runs it has package identity.

Packaged vs Unpackaged is already well defined at https://learn.microsoft.com/windows/apps/package-and-deploy/packaging/#packaged-vs-unpackaged-apps and is all about if a running process HAS or LACKS package identity in its process token.

Rows 3+4 are an entirely independent concept - the form of the Windows App Runtime consumed by a process:

  • Framework-Dependent -- Windows App Runtime is used from WinAppSDK's installed MSIX packages
  • Self-Contained Windows App Runtime is used via a redistributable copy colocated with the consuming application

A more convenient set of lingo is WinAppSDK/MSIX vs WinAppSDK/SelfContained.

If I make a packaged application using WinAppSDK/SelfContained then my packaged app includes a copy of the Windows App Runtime inside my package for use by my packaged app. In that case...
*

  • MyAwesomeApp.exe is a Packaged app
  • MyAwesomeApp.exe is in MyAwesomeApp.msix
  • Windows App Runtime (Microsoft.WindowsAppRuntime.dll etc) is also in MyAwesomeApp.msix

If MyAwesomeApp is packaged but using WinAppSDK/MSIX then...
*

  • MyAwesomeApp.exe is a Packaged app
  • MyAwesomeApp.exe is in MyAwesomeApp.msix
  • Windows App Runtime (Microsoft.WindowsAppRuntime.dll etc) is is WinAppSDK's MSIX packages*

* Saying 'Framework-Dependent' or WinAppSDK/Framework is misleading for multiple reasons. WinAppSDK is currently composed of multiple MSIX packages - Framework, Main, Singleton, DDLM. It's not just a Framework package. WinAppSDK/MSIX is the more accurate phrase, avoiding the misperceptions conveyed by citing any particular packages or package types making up WinAppSDK's runtime.

| **Unpackaged** | App deployed without MSIX packaging, no package identity |
| **Self-Contained** | App bundles the WinAppSDK runtime, no framework package dependency |
| **Framework-Dependent** | App depends on the WinAppSDK framework package being installed |

## App Notifications

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `AppNotificationManager.Register()` | Y | Y | Y | Packaged: uses manifest CLSID. Unpackaged: registers caller process as COM server |
| `AppNotificationManager.Register(String, Uri)` | N | Y | Y | Unpackaged only. Allows custom display name and icon |
| `AppNotificationManager.Show()` | Y | Y | Y | |
| `AppNotificationManager.GetAllAsync()` | Y | Y | Y | |
| `AppNotificationManager.RemoveAllAsync()` | Y | Y | Y | |
| `AppNotificationManager.Setting` | Y | Y | Y | `DisabledByManifest` status only applies to packaged apps |
| Image protocols in notifications | Y (ms-appx) | P (file:// only) | P (file:// only) | Unpackaged apps cannot use ms-appx:// protocol |

## Push Notifications

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `PushNotificationManager.CreateChannelAsync()` | Y | Y | P | Self-contained may not support push due to API limitations |
Copy link
Copy Markdown
Member

@DrusTheAxe DrusTheAxe Feb 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This (and other entries in this table) say 'P' but no explanation what it means

| `PushNotificationManager.Register()` | Y | Y | P | Unpackaged requires bootstrapper initialization |
| `PushNotificationManager.Unregister()` | Y | Y | P | |
| Raw push notifications | Y | Y | P | |
| Visual cloud toasts | Y | Y | P | |

## App Lifecycle

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `AppInstance.GetCurrent()` | Y | Y | Y | |
| `AppInstance.FindOrRegisterForKey()` | Y | Y | Y | |
| `AppInstance.Restart()` | Y | Y | Y | |
| `AppInstance.GetActivatedEventArgs()` | Y | Y | Y | |
| `ActivationRegistrationManager` | Y | Y | Y | Registration mechanisms differ by app type |

## MRT Core (Resources)

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `ResourceLoader` | Y | Y | Y | Unpackaged: loads from `[module].pri` or `resources.pri` |
| `ResourceManager` | Y | Y | Y | |
| `ApplicationLanguages.PrimaryLanguageOverride` | Y | Y | Y | Packaged: persisted across sessions. Unpackaged: process-lifetime only |
| `ApplicationLanguages.ManifestLanguages` | Y | N | N | Requires package manifest; returns empty list for unpackaged |

## Application Data

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `ApplicationData.GetDefault()` | Y | N | N | Requires package identity |
| `ApplicationData.GetForUnpackaged()` | N | Y | Y | Unpackaged apps only |

## Deployment

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `DeploymentManager.GetStatus()` | Y | Y | Y | |
| `DeploymentManager.Initialize()` | Y | Y | N | Not needed for self-contained |
| Bootstrap API (`MddBootstrapInitialize`) | N/A | Y | N/A | Framework-dependent unpackaged apps only |

## Windowing

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `AppWindow` | Y | Y | Y | |
| `DisplayArea` | Y | Y | Y | |
| Placement APIs (experimental) | Y | Y | Y | Requires WinAppSDK 2.0 Experimental |

## Version Info

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `ReleaseInfo` | Y | Y | Y | Available since WinAppSDK 1.8 stable |
| `RuntimeInfo` | Y | Y | Y | Available since WinAppSDK 1.8 stable |

## Named Object Security

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `GetSecurityDescriptorForAppContainerNames` | Y | Y | Y | Primarily useful for sharing between packaged and Win32 processes |

## Storage Pickers (Experimental)

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| `FolderPicker` | Y | Y | Y | WinAppSDK pickers support both packaged and unpackaged |
| `FileOpenPicker` | Y | Y | Y | |
| `FileSavePicker` | Y | Y | Y | |

## Windows Copilot Runtime (WCR)

| API | Packaged | Unpackaged | Self-Contained | Notes |
|-----|----------|-----------|----------------|-------|
| Phi Silica / LanguageModel | Y | Y | N | Requires Copilot+ hardware; x64/ARM64 only (no x86) |
| ImageDescriptionGenerator | Y | Y | N | Requires Copilot+ hardware |
| TextRecognizer | Y | Y | N | Requires Copilot+ hardware |
| ImageSuperResolution | Y | Y | N | Requires Copilot+ hardware |

## Key Considerations

### Packaged vs Unpackaged

- **Packaged apps** have a package identity, which enables features like
ms-appx:// URI scheme, ApplicationData.GetDefault(), manifest-based
notification registration, and ManifestLanguages.
- **Unpackaged apps** must use alternative registration paths and cannot rely
on package identity. Some APIs provide unpackaged-specific alternatives
(e.g., `ApplicationData.GetForUnpackaged()`).

### Self-Contained vs Framework-Dependent

- **Self-contained** apps bundle the WinAppSDK runtime and do not need the
framework package installed. However, some APIs that depend on framework
package services (Push Notifications, WCR) may have limited support.
- **Framework-dependent** apps require the WinAppSDK framework package to be
installed on the target machine. All APIs are available when the correct
framework version is present.

### Minimum OS Version

- Windows App SDK generally requires Windows 10 version 1809 (build 17763)
or later.
- Some features require newer Windows versions. Check the individual API
documentation for specific version requirements.
- WCR features require Windows 11 with Copilot+ capable hardware.