Microsoft.Windows.Management.Deployment Namespace

This namespace provides MSIX package management APIs comparable to those in the Windows.Management.Deployment namespace, but with additional functionality, improved developer experience, and performance optimizations.

These Windows Runtime (WinRT) APIs allow you to deploy and manage software as MSIX packages. You can install, update, uninstall, enumerate, and otherwise manage packages. Here are the scenarios that the APIs focus on:

  • Stage a package
  • Register a package
  • Add/update a package
  • Remove a package
  • Repair a package
  • Reset a package
  • Provision a package
  • Deprovision a package

Additional functionality includes:

  • IsReadyXxx. Determine whether a package is ready for use.
  • EnsureReady. Determine whether a package is ready for use and, if not, make it so.
  • IsPackageRegistrationPending. Determine whether there's an update waiting to register.
  • PackageSets. Batch operations.
  • PackageRuntimeManager. Batch operations for use at runtime via dynamic dependencies.
  • Usability. Quality-of-Life enhancements.

API structure

Methods to drive deployment activity typically follow the pattern:

<verb>Package[Set][By<Type>][Suffix]Async(target, options)

The following verbs are supported:

  • Is...Ready[OrNewerAvailable]
  • Ensure...Ready
  • Add
  • Stage
  • Register
  • Remove
  • Repair
  • Reset
  • Provision
  • Deprovision

Those methods accept their target package(s) as their first parameter. That parameter can be various types of information including:

  • Filename
  • Path
  • PackageFamilyName
  • PackageFullName
  • Uri

![NOTE] Methods with a target of a URI are named ...ByUri....

![NOTE] Methods with a target of a PackageFamilyName are named ...ByPackageFamilyName....

![NOTE] Methods with a target of a PackageFullName are named ...ByPackageFullName....

![NOTE] Methods with no ...By<Type>... qualifier accept a string that can contain one or more types of identifiers. Those can vary for different verbs. See the API documentation for the specific target types supported by each method.

These methods accept options as a matching <verb>Package[Set]Options type; for example, AddPackageAsync(string packageUri, AddPackageOptions options).

The following table shows the supported permutations of verbs and targets:

Verb Path Filename PackageFamilyName PackageFullName file: http(s): ms-uup: PackageSet
IsReady X X OS/WAS WAS X X WAS WAS
IsReadyOrNewerAvailable X X OS/WAS WAS X X WAS WAS
EnsureReady X X X X X X WAS WAS
Add OS/WAS X X X OS/WAS OS/WAS OS/WAS WAS
Stage OS/WAS X X X OS/WAS OS/WAS OS/WAS WAS
Register WAS OS/WAS OS/WAS OS/WAS OS/WAS X OS/WAS WAS
Remove X X WAS OS/WAS X X OS/WAS WAS
Repair X X WAS WAS X X WAS WAS
Reset X X WAS WAS X X WAS WAS
IsProvisioned X X OS/WAS X X X WAS WAS
Provision X X OS/WAS X X X WAS WAS
Deprovision X X OS/WAS X X X WAS WAS

Legend:

  • OS = Supported by Windows (OS) APIs in the Windows.Management.Deployment.PackageManager class.
  • WAS = Supported by Windows App SDK APIs in the Microsoft.Windows.Management.Deployment.PackageDeploymentManager class.
  • X = Not supported

Usability

The package management APIs in the Windows App SDK (Microsoft.Windows.Management.Deployment) provide several quality-of-life enhancements over the package management APIs in Windows.Management.Deployment (for example, PackageManager). These include:

  • PackageManager.AddPackageByUriAsync fails, returning ERROR_INSTALL_PACKAGE_DOWNGRADE, if a newer version of the package is already installed. But PackageDeploymentManager.AddPackageByUriAsync succeeds because it treats the request as "install this package or a higher version", in the way that dependencies and other package references are routinely handled.
  • PackageManager.AddPackageByUriAsync fails, returning ERROR_PACKAGE_ALREADY_EXISTS, if that exact version of the package is already installed. PackageDeploymentManager.AddPackageByUriAsync succeeds because the requested package is installed.
  • Many PackageManager operations accept a target package as a file, but require it expressed as a Uri. PackageDeploymentManager provides overrides also accepting it as a String.
  • PackageManager.RemovePackageByFullNameAsync fails if the specified package isn't found. PackageDeploymentManager succeeds because the requested package isn't present at the end of the operation.
    • This is because of the core deployment principle that it doesn't matter the previous state of the system; only that the desired end state is achieved.
  • PackageManager methods accept inconsistent (and often inconvenient) permutations of expressing a target package. For example, PackageManager supports removing a package by package full name, but not by package family name. PackageDeploymentManager provides a richer API accepting additional identifiers.

Platform support

These APIs are available only on Windows 10, version 2004 (10.0; Build 19041) and later.

A subset of functionality is available on newer releases. For example, AddPackageOptions.ExpectedDigests requires Windows 11, version 22H2 (10.0; Build 22621) or later. Any functionality requiring a release of windows newer than the Windows 10, version 2004 (10.0; Build 19041) baseline has affordances to detect at runtime whether the current platform supports the feature, for example:

var options = new AddPackageOptions();
if (options.IsLimitToExistingPackagesSupported)
{
    options.LimitToExistingPackages = true;
}

Classes

AddPackageOptions

Specifies the deployment options that you can configure when you use the AddPackageByUriAsync method to add a package, package manifest, or App Installer file.

EnsureReadyOptions
PackageDeploymentManager

Manages the software available to a user.

PackageDeploymentResult

Provides the result of a deployment request.

PackageRuntimeManager

The PackageRuntimeManager class provides Dynamic Dependency support for PackageSet operations, especially when the caller might not know the exact package(s) involved—for instance, when targeting packages via ms-uup:. PackageRuntimeManager determines the packages involved for a PackageSet, and dynamically adds them to the caller's package graph.

PackageSet

Class that represents a package set, which is a group of packages to be operated on with one request. A package set provides a convenient means to perform multiple operations.

![NOTE] There's no ordering guarantee of items processed in a PackageSet.

PackageSetItem

Represents a package in a PackageSet.

PackageSetItemRuntimeDisposition
PackageSetRuntimeDisposition
PackageVolume

Represents a Package storage volume.

ProvisionPackageOptions
RegisterPackageOptions

Specifies the deployment options that you can configure when you use the RegisterPackageByUriAsync method to register a Package.

RemovePackageOptions
StagePackageOptions

Specifies the deployment options that you can configure when you use the StagePackageByUriAsync method to stage a package.

Structs

PackageDeploymentProgress

Contains progress information for the deployment request.

Enums

PackageDeploymentFeature
PackageDeploymentProgressStatus

Defines constants that specify the progress status of the deployment request.

PackageDeploymentStatus

The status of the deployment request.

PackageReadyOrNewerAvailableStatus

Defines the stub behavior for an app package that is being added or staged.

StubPackageOption

Defines constants that specify the stub behavior for an app package that's being added or staged.