1. Background

March 19, 2026 ยท View on GitHub

1. Background

Windows App SDK supports deployment as a set of MSIX packages for use at runtime. This document outlines the list of packages and their rules and roles.

2. MSIX Packages

Windows App SDK is distributed as multiple MSIX packages:

  1. Framework
  2. Main
  3. Singleton
  4. Dynamic Dependency Lifetime Manager (DDLM)

2.1. Roles

2.1.1. Role - Framework

The Framework package is the API delivery vehicle for Windows App SDK. The vast majority of code in the project is found here.

Framework packages support concurrent behavior. A user may have multiple versions of a framework package in use across processes (process1 using 1.0.1.0, process2 using 1.0.2.0, ...). Updates can be registered for a user without disrupting running apps. Windows points running apps to updated Framework packages non-disruptively (e.g. when an app's not running), colaescing apps to newer versions over time (not necessarily instaneously). This provides for a very flexible servicing model.

2.1.2. Role - Main

The Main package supplements the Framework package, for when functionality is needed but can't be delivered via the Framework package. Mechanisms include Packaged COM, app services, app extensions, background tasks, startup tasks executing on user login, ApplicationData for data storage scoped to Windows App SDK (not any particular app using Windows App SDK), and more.

The primary scenarios include:

  • Brokered Access -- processes running in an AppContainer requiring access to resources that cannot be access from within the AppContainer can use a 'helper process' running at MediumIL and doing work on the API's behalf. cannot do for itself (i.e. brokered access to a resource).
  • Long-Running Process (aka user service) -- functionality requiring a long-running process (especially if its lifetime isn't directly coupled to an app's lifetime).

Main packages don't support side-by-side behavior for a user. A user can only have 1 (or 0) Main packages in a package family registered at a time. Thus if a user has v1.0.0.0 registered when 1.0.0.1 is registered it's an update, ending with the user having v1.0.0.1 registered instead of v1.0.0.0. This poses servicing challenges, as updating the Main package requires any running processes from the existing Main package to be terminated.

For these reasons Windows App SDK developers are strongly encouraged to only rely on the Main package when necessary.

If a process from the Main package is necessary, it should be short-lived or support a save/restore execution model. The former shrinks the possibility a running process when a servicing event occurs. The latter ensures if Main package processes are running when a servicing event occurs, the running processes can be terminated (e.g. via DeploymentOptions.ForceTargetApplicationShutdown) to allow the servicing event to occur and restarted upon its completion, with only a transient (and possibly unnoticed) interruption of service.

Further, if/when the Main package is necessary, Windows App SDK developers are encouraged to put as little as practical in the Main package and use the Framework package as much as possible. For example, if a StartupTask is needed you can declare the StartupTask in the Main package's appxmanifest.xml and provide an executable with a trivial 1% implementation e.g.

int WINAPI WinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, PWSTR pCmdLine, int nCmdShow)
{
    return MyFeatureWinMain(hInstance, hPrevInstance, pCmdLine, nCmdShow);
}

and export MyFeatureWinMain from a DLL in the Framework package to get the implementation's other 99%.

2.1.3. Role - Singleton

The Singleton package supplements the Main package, for when functionality is needed by a single process spanning all versions of Windows App SDK.

The Singleton package is a main package so the same guidance applies to the Singleton as to the Main package -- Windows App SDK developers are strongly encouraged to only rely on the Singleton package when necessary. See (2.1.2. Role- Main) for more details.

The Singleton package's content is used by ALL versions of Windows App SDK registered to the user so additional caution is advised.

Only the highest version of the Singleton package will be installed for a user, e.g. if Windows App SDK 1.0, 1.1 and 2.0 (Stable) are installed on an x86 system, the user will have registered...

  • Microsoft.WindowsAppRuntime.1.0
  • Microsoft.WindowsAppRuntime.1.1
  • Microsoft.WindowsAppRuntime.2
  • MicrosoftCorporationII.WinAppRuntime.Main.1.0
  • MicrosoftCorporationII.WinAppRuntime.Main.1.1
  • MicrosoftCorporationII.WinAppRuntime.Main.2
  • MicrosoftCorporationII.WinAppRuntime.Singleton (version 2.0)
  • Microsoft.WinAppRuntime.DDLM.0.146.711.0-x8
  • Microsoft.WinAppRuntime.DDLM.1000.328.1510.0-x8
  • Microsoft.WinAppRuntime.DDLM.0.510.333.0-x8

Singleton package content MUST be backwards compatible across all releases due to the Singleton package's singular nature

2.1.4. Dynamic Dependency Lifetime Manager (DDLM)

The Dynamic Dependency API resolves a package dependency to a specific framework package and make it available for a process, but Windows doesn't know the package is in use by this process. Lacking this "package in use" knowledge, Windows could service the package (remove, remediate, repair, ...) in negatively impactful ways. To prevent this (without servicing Windows) we need...

  1. ...a running process running with package identity...
  2. ...with an appxmanifest.xml declaring a <PackageDependnecy> on the framework package...
  3. ...running for as long as the framework package is used by the app.

This is accomplished for the Microsoft.WindowsAppRuntime framework package via a Packaged COM out-of-process (OOP) server in a DDLM package, selected and managed via the Bootstrap API. See the Dynamic Dependency spec for more details.

3. Package Naming

Windows App SDK's MSIX packages use the following naming rules for package identity:

  • Name = Microsoft.WindowsAppRuntime[.SubName].<Major>[-VersionTag][ChannelBuildNumber]
  • Publisher = "CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US"

where

  • SubName -- optional package sub-name. Use to distinguish amongst the different packages
  • Major -- major version of the release, e.g. "1" for Windows App SDK 1.0
  • VersionTag -- optional version tag to distinguish amongst channels, e.g. "-preview" for Windows App SDK Preview
  • ChannelBuildNumber -- optional Build number (up to 2 digits, base 36[0-9a-z], no leading 0s) designating which build number of the channel for the Major release we are on

3.1. Package Naming - SubName

The following SubName values are used:

SubNamePackageExample
FrameworkMicrosoft.WindowsAppRuntime.2-experimental10
MainMainMicrosoftCorporationII.WinAppRuntime.Main.2-e10
SingletonSingletonMicrosoftCorporationII.WinAppRuntime.Singleton-e10
DDLMDynamic Dependency Lifetime Manager (DDLM)Microsoft.WinAppRuntime.DDLM.2.3.11.0-x6-e10

3.2. Package Naming - Main

The Main package follows a different naming scheme

  • Name = MicrosoftCcorporationII.WinAppRuntime.Main.<ReleaseMajor>[-ShortVersionTag]

where

  • ReleaseMajor = project release major version number. See the MSIX Package Versioning for more details.
  • ShortVersionTag = short form of the VersionTag

ShortVersionTag is derived from a VersionTag by combining the 1st letter and up to the last 2 digit (depending on build number) for non-Stable channels (ShortVeresionTag is blank for the Stable channel, just like VersionTag).

3.3. Package Naming - Singleton

The Singleton package follows a naming scheme similar to the Main package:

  • Name = MicrosoftCorporationII.WinAppRuntime.Singleton[-ShortVersionTag]

The package family is the same across all versions of Windows App SDK. As a main package, only one Singleton package can be registered at a time for a user and by its nature it's meant to be used with all versions of Windows App SDK registered for a user. Thus its package Name is rather simple compared to other package Names, lacking any version information.

See 2.1.3. Role - Singleton for more information.

3.4. Package Naming - DDLM

DDLM packages follow a different naming scheme

  • Name = Microsoft.WinAppRuntime.DDLM.<Version>-<ShortArchitecture>[-ShortVersionTag]

where

  • Version = MSIX version number (which matches the project release version). See the MSIX Package Versioning for more details.
  • ShortArchitecture = short form of the Architecture (x6=x64, x8=x86, a6=arm64)
  • ShortVersionTag = short form of the VersionTag

ShortVersionTag is derived by combining the 1st letter of the versionTag and the entire channelBuildNumber for non-Stable channels (ShortVeresionTag is blank for the Stable channel, just like VersionTag).

string ToShortVersionTag(string versionTag, string channelBuildNumber)
{
    if (String.IsNullOrEmpty(versionTag))
    {
        return versionTag;
    }
    string prefix = versionTag.substr(0, 1);
    return prefix + channelBuildNumber;
}

4. Package Versioning

See the MSIX Package Versioning decision document for more details.