App packages and deployment (Windows Store apps)

As a developer, you don't write routines to install or uninstall your Windows Store app. Instead, you package your app and submit it to the Windows Store. Users acquire your app from the Windows Store as an app package. Windows uses info in an app package to install the app on a per-user basis, and ensure that all traces of the app are gone from the device after all users who installed the app uninstall it.

An app package is a container based on the Open Packing Conventions (OPC) standard. OPC defines a structured way to store data and resources for the app by using a standard ZIP file. For info about how to use Microsoft Visual Studio to deploy app packages, see Deploying Windows Store apps from Visual Studio.

Windows Store app deployment

The Windows Store app model is a declarative state-driven process that provides all installation and update data and instructions for an app in a single package. In this declarative model, deployment operations are reliable. The files shipped in the package are immutable, which means that they haven't been modified since they were delivered to the computer. Because the package owner doesn't need to write custom actions and code, the number of failure points are reduced.

During the update process, a new version of the app is downloaded and installed to the user’s profile; immediately afterwards the old version is removed from the computer. In contrast to Windows Installer, there is no concept of patch files or any other files that are used to deploy a Windows Store app.

Because Windows Store apps are installed into a user’s profile, each user has complete control over their Windows Store apps. Apps can be installed, updated, and removed without affecting any other user’s apps on the computer.

Windows Store app packages – .appx

All the components that define a Windows Store app are stored in an appx package. This appx package has a .appx file extension and is the unit of installation for a Windows Store app. Appx packages are ZIP-based container files that are defined as a subset of the ISO and ECMA Open Packaging Conventions (OPC) standards. Each appx package contains the app’s payload files plus info needed to validate, deploy, manage, and update the app. From a high-level view, each Windows Store app package contains these items:

App payload

App code files and assets

Payload files are the code files and assets that you author when you create your Windows Store app.

App manifest

App manifest file (AppxManifest.xml)

The app manifest declares the identity of the app, the app's capabilities, and info for deploying and updating. For more info about the app manifest file, see App package manifest.

App block map

App package’s block map file (AppxBlockMap.xml)

The block map file lists all the app files contained in the package along with associated cryptographic hash values that the operating system uses to validate file integrity and to optimize an update for the app. For more info about the block map file, see App package block map.

App signature

App package’s digital signature file (AppxSignature.p7x)

The app package signature ensures that the package and contents haven't been modified after they were signed. If the signing certificate validates to a Trusted Root Certification Authorities Certificate, the signature also identifies who signed the package. The signer of the package is typically the publisher or author of the app.

These preceding items comprise a fully self-contained Windows Store app that can be deployed to Windows 8 and later. You create the app payload and manifest files for your app. When Visual Studio packages your app, it automatically adds the app block map and signature files to the package. But you can also use the standalone MakeAppx and SignTool utilities if you want to manually package your app. These sections describe how to package and deploy Windows Store apps.

• How to create an app package
• How to create an app package signing certificate
• How to sign an app package using SignTool
• How to troubleshoot app package signature errors
• How to programmatically sign an app package
• How to develop an OEM app that uses a custom file

Package identity

One of the most fundamental pieces of the app package is the 5-part tuple that defines the package. This tuple is known as the package identity and consists of this data:

Name

A general name that is used for the app package. For example, "myCompany.mySuite.myApp".

Note  This name isn't necessarily what is displayed on the app tile.

Publisher

The publisher refers to the publisher of the Windows Store app. In most cases, the publisher is the same as the account that was used to register for a Windows 8 developer account.

Version

A four part version descriptor (major.minor.build.revision) that is used to service future releases of the app. For example, "1.0.0.0".

Note  You must use all four parts of the version descriptor.

ProcessorArchitecture

The target architecture of the app package. This value can be "x86", "x64", "arm", or "neutral". In many cases, this field can be "neutral" to represent all architectures.

ResourceID

Optional.

A publisher-specified string that specifies the resources of the app package. This part of the tuple is used primarily if the app package has assets that are specific to a region, such as, languages.

If you are creating the package manually, see the Identity element.

Package format

Here we describe details about app packages, that is, the .appx file format.

App packages are read-only

Although app packages are based on a subset of OPC, we recommend not to use existing APIs for manipulating OPC or ZIP files to edit app packages. After you create an app package, treat the package as read-only. The Visual Studio and MakeAppx processes that create .appx packages automatically generate and add the AppxBlockMap.xml file to the package. If you change any of the package contents, you need to update the package’s block map file to match. To create a new package and block map file, you must rebuild the package with Visual Studio, the MakeAppx pack command, or the Windows 8 native-code IAppxPackageWriter APIs.

App package payload file names

To comply with OPC, the file path names for all files that are stored in an app package must be Uniform Resource Identifier (URI) compliant. File paths that are not URI compliant need to be percent-encoded when stored in an app package, and decoded back into the original file path when extracted from the package. For example, consider this payload file with a path and name that contains embedded spaces and URI reserved characters '[' and ']':

\my pictures\kids party[3].jpg

When you store this payload file in the app package, the path for the file becomes:

/my%20pictures/kids%20party%5B3%5D.jpg

Visual Studio, the app packager (MakeAppx), and the Packaging APIs handle the percent-encoding and decoding of file paths automatically. If you attempt to extract files directly from an app package by using general ZIP utilities or APIs, the file paths might remain percent-encoded. So we recommend that you extract files from an app package by using either the MakeAppx unpack command or the IAppxPackageReader APIs.

App package capacities

App packages support apps up to these capacity limits:

App package reserved path and file names

These path and file names are reserved, so don't use them for app payload files:

App package digital signatures

You must sign every app package before users can install them. While app package signing is partly automated through Authenticode, you must control the following features when you sign app packages:

• The subject name of the code signing certificate must match the Publisher attribute that is specified in the Identity element of the AppxManifest.xml file in the app package.
• The hash algorithm that is used to sign the app package must match the hash algorithm that is used to generate the AppxBlockMap.xml file in the app package. This hash algorithm is specified in the HashMethod attribute of the BlockMap element.
• An app package can't be time stamped independently of signing. It must be time stamped during signing if time stamping is desired.
• App packages don't support multiple enveloped signatures.

The signature of a package determines how the Windows Store app is licensed. How an app is licensed affects how it can be installed and run, so even two app packages with the same package identity might not be treated as equivalent during installation. For example, you can't install an app package with the same package identity as another already installed app, if it doesn't also have the same signature.

Declarative install

Windows Store app deployment is an entirely declarative process that relies on the app package manifest. You use the app package manifest to capture your desired integration with the operating system. For example, you use the app package manifest to declare the need to use a file type association, such as .jpg, on the operating system.

By doing this, Windows can completely manage the Windows Store app deployment process so that it’s a consistent, dependable experience for each user on a multitude of devices. Moreover, by having a declarative installation Windows Store app, uninstallation of the app becomes deterministic and repeatable.

Within the app package manifest, you can declare a wide range of technologies as part of Windows Store app installation.

App pre-requisites

To successfully deploy an app, the operating system must satisfy all of that app’s pre-requisites that are referenced in the app package manifest. For example, if a version of Windows exposes a new API that a Windows Store app calls, the app declares a pre-requisite on that specific minimum version operating system. In this case, the proper operating system must be present on the target computer before the app can be installed. In Windows 8 and later, you can declare these key types of pre-requisites in the app package manifest:

OSMinVersion

Specifies the minimum version of the Windows operating system and app model platform where this app is permitted to run.

OSMaxVersionTested

Specifies the maximum version of the Windows operating system where this app was tested by the developer and known to be in a working state. This pre-requisite field is used by the operating system to determine if there is any app compatibility issue that might arise during the app’s usage. For example, if the app calls an API from the Windows 8 SDK and the API was later changed in a subsequent version of Windows, the app might behave incorrectly. This pre-requisite field helps ensure that the operating system can identify and correct this behavior so the app continues to function on all subsequent versions of the operating system.

Capabilities

Windows Store apps that need programmatic access to user resources such as the Pictures library or connected devices such as a webcam, must declare the appropriate capability. An app requests access by declaring capabilities in its app package manifest. You can declare capabilities by using the Manifest Designer in Visual Studio, or you can add them manually to the package manifest as described in How to specify capabilities in a package manifest. For more info about capabilities, see App capability declarations.

Dependencies

The Windows Store hosts a unique set of app packages that contain Windows components that service independently of Windows. Windows Store apps can use these app packages by declaring a dependency in their app package manifest. These Windows components contained in app packages hosted by the Windows Store are called Windows component libraries. The Windows Store manages the process of ensuring that the correct version of the Windows component library is present when the app is installed on a Windows 8 computer. These libraries, which include Windows Library for JavaScript, C++ Runtime Libraries (CRT), and PlayReady DRM, are essential to the creation of Windows Store apps. When an app deploys from the Windows Store, Windows satisfies the dependency declaration by downloading and installing the appropriate Windows component library with the app that is being downloaded from the Windows Store. For side loading Windows Store apps for testing or enterprise deployment, the Windows component library app package must be supplied and specified during deployment of the app package.

Per user deployments

Windows Store app deployments are per user, which means they only impact the account of the user who installed them. Furthermore, in multi-user scenarios, users don't have any knowledge of what was installed for any other user. For example, suppose UserA installed the Notepad app while UserB installed the Calculator app. In this scenario, UserA and UserB have no knowledge into other apps installed to the same computer (app isolation).

App isolation

App isolation on the operating system is only limited to the user portion of the Windows Store app. All other data from the app is stored in a location that the operating system can access. For example, suppose UserA installed the Calculator app and UserB also installed the Calculator app; in this scenario, only one copy of the Calculator app binaries are stored on the drive (%ProgramFiles%\WindowsApps), and both users have access. UserA doesn't see UserB’s app data and vice versa. While the runtime binaries are shared, the app data is still isolated.

Note  The %ProgramFiles%\WindowsApp directory can't be changed. This also includes the underlying %ProgramFiles% directory as well as the %ProgramData% and %UserProfile% directories.

Multi version existence

In addition to containing all the Windows Store app binaries for all users on the system, the WindowsApps directory can also contain multiple versions of the same Windows Store app. For example, suppose both UserA and UserB installed the Notepad app, and UserA updated to version 2 of the Notepad app while UserB didn't. In this scenario, two versions of the Notepad app exist on the operating system. Because only one version is installed for each user, the multiple versions don't conflict with each other.

Note  This behavior is also applicable to dependency packages.

Deployment for Windows Store apps

These sections describe the flow of installing, updating, and removing Windows Store apps.

Installing Windows Store apps

This figure shows the flow of installing Windows Store apps:

The Windows Store app deployment process occurs in multiple phases. Initially, Windows acquires and validates the app manifest, app block map, and app signature. Next, Windows checks the app package’s deployment criteria to ensure that the app deployment will be successful. Next, Windows stages the package binaries to the WindowsApps directory. Finally, Windows registers the package into the user's account.

Deployment checks (validation)

This figure shows the phase where Windows performs deployment checks:

After the user starts to install a Windows Store app, Windows must complete these checks before the deployment process can begin:

OSMinVersion must be satisfied

You specify app pre-requisites within the app package manifest. They express the requirement for a specific minimum operating system version to be satisfied. For more info about app pre-requisites, see App pre-requisites.

App dependencies must be satisfied

Windows Store apps can express a dependency on another app package for added functionality that the app needs. For more info about app dependencies, see Dependencies.

Disk space must be sufficient

Each Windows Store app requires a certain amount of disk space to be present so the app can deploy. If there isn't enough disk space present on the computer to deploy the package, deployment fails.

App isn't already deployed

Within the context of the specific user that installed the Windows Store app, the app can't be installed again so a check whether the app is not installed already must be performed.

App assets must pass signature check

Using the already validated BlockMap, each file in the app package must have its integrity checked.

Package staging

This figure shows the phase where Windows stages the package:

After the app model determines that the package can deploy on the computer, Windows stores the package’s contents on the disk in the %ProgramFiles%\WindowsApps directory in a new directory named after the package identity:

<Package Name>_<Version>_<Architecture>_<ResourceID>_<Publisher Hash>

The staging process occurs via a set of requests made by the deployment engine to the source of the package’s location. These requests are then satisfied by the source and returned to the deployment engine where they are decompressed, validated against the BlockMap, and copied into the appropriate file.

Package registration

This figure shows the phase where Windows registers the package:

Package registration is the final phase in the deployment process. During this phase, the extensions that are declared in the manifest are registered with the operating system. This enables the app to deeply integrate with the operating system. For example, if you want your app to be able to open .txt files, declare a FileTypeAssociation extension as XML in your app package manifest and specify .txt as the file type. At deployment time, this XML is translated into the set of system changes that need to occur to properly register the app to handle .txt files. These changes are then made on behalf of the app, by the app model. The app model supports many different extensions. For more info about these extensions, see App contracts and extensions.

Updating Windows Store apps

This figure shows the flow of updating Windows Store apps:

The updating workflow is similar to that of Installing Windows Store apps, but here are a few key differences that make updating unique.

Deployment checks for updating

This figure shows the phase where Windows performs deployment checks in updating:

If the currently installed app package’s version is greater than or equal to what the user is trying to install, deployment won't succeed.

Package staging (delta downloads)

This figure shows the phase where Windows stages the updated package:

The staging process during update is similar to the typical staging process during installation. But the key difference is that a pre-existing version of the package is already installed on the operating system. After the pre-existing package installation completes, a set of payload files are downloaded and copied to the computer. In many cases, many of those payload files won’t change or will only slightly change in the updated version of the app package. You can use those payload files to construct the updated app package content and assets. Because the BlockMap structure of the app package contains a list of hashes for each block of each file, Windows can compute the precise set of changes on a block level via a comparison of the former and new app BlockMap files. Here are the possible outcomes as a result of this comparison:

A file was unchanged

The file is hard linked to the updated package folder location.

Blocks in a file were unchanged

The unchanged blocks are copied over into the updated package folder.

Blocks in the file were changed

The changed blocks are marked to be downloaded from the source.

An entire file is new

The entire file will be downloaded from the source.

A file no longer exists

The file will not be used for the update at all.

After the comparison completes, all the data that can be preserved is hard linked or copied and any new data is downloaded from the source and used to make the updated files.

Package registration for updating

This figure shows the phase where Windows registers the updated package:

When you update a package’s registration, Windows also needs to update registrations of the previous versions. The app model automatically updates any existing extension registrations, removes obsolete registrations, and registers new extensions based on the declarations that are present in the manifests of the former and new versions of the app.

Apps in use

The process of de-registering an app package from the operating system involves removing the internals that allow Windows to launch the Windows Store app. In some certain cases, the app can be running while the update occurs. In this scenario, the deployment engine requests to suspend and subsequently terminate the app. The update process either succeeds or fails depending on the outcome of that request. In the case where the operations succeed, the app is also prevented from launching for the short duration of time while the registration of the new app package and de-registration of the former app package occurs. After this phase completes, the app is re-allowed to launch.

App data

App data is an entity that has a version that is outside of the actual Windows Store app. As such, if the ApplicationData.Version wasn't updated along with the update for the Windows Store app, the app state isn't affected by the update for the Windows Store app.

Package de-staging

This figure shows the phase where Windows de-stages the updated package:

After the registration operation successfully completes, if the pre-existing version of the package is not being used by any other user on the operating system, the package is marked for removal from the operating system. Initially, Windows copies the pre-existing version's app package folder into the %ProgramFiles%\WindowsApps\Deleted directory. When no other deployment operations are ongoing, Windows deletes the pre-existing version's app package folder.

Note  In multi-user scenarios, the app package might still be installed on the operating system for another user. In this case, the package content isn't de-staged from the operating system until all users have removed it.

Removing Windows Store apps

This figure shows the flow of removing Windows Store apps:

Similarly to the way packages are installed per user on a computer, they are also only removed per user. If the Windows Store app is installed for multiple users, it is only de-registered for the current user. For example, if UserA and UserB have the Calculator app installed and UserA uninstalls the app, it is removed only for UserA and not for UserB. The removal process consists of the same basic phases as the updating process.

Package de-registration

This figure shows the phase where Windows de-registers the removed package:

The de-registration process is where the Windows Store app’s integration into the user’s account is removed. Any associated data that was installed to the user’s account, such as app state, is also removed. Similar to the updating process, the deployment engine must request the app be suspended and terminated via the Process Lifetime Manager (PLM) so the app can be de-registered from the user’s account.

Note  After the PLM returns, the removal operation continues to de-register the Windows Store app from the user’s account. The operation continues even if the PLM was not successful.

Package de-staging

This figure shows the phase where Windows de-stages the removed package:

After the de-registration operation successfully completes, the package, if it is not being used by any other user on the operating system, is marked for removal from the operating system. Initially, Windows copies the package's app package folder into the %ProgramFiles%\WindowsApps\Deleted directory. When no other deployment operations are ongoing, Windows deletes the package's app package folder.

Note  In multi-user scenarios, the app package might still be installed on the operating system for another user. In this case, the package content isn't de-staged from the operating system until all users have removed it.

Inventory of packages

As Windows Store apps are installed, updated, and removed, a given user can at any time view which app packages are installed or pre-staged. A user with Administrator privileges can also determine which app packages are installed for all users on the system. For more info about how to inventory packages on the operating system, see Tools and PowerShell cmdlets.

Frequently asked questions

How do I install multiple packages simultaneously?

You can install multiple packages by calling the Packaging APIs multiple times or once for the entire set of packages to be installed. The underlying implementation of the app model allows for any number of app packages to be awaiting deployment. But only up to 3 concurrent staging operations per user (total of 7 simultaneous stage operations per operating system) and 1 registration operation per operating system is allowed.

What happens if the package is already installed?

If the package is already installed, a package with the same package identity that is registered for the current user’s account already exists. In this scenario, the identical package isn't installed.

Can an update be made mandatory?

You can't make an update mandatory via the app model. The update model is strictly optional. In rare cases, the Windows Store can deem an update appropriate to be distributed as a higher priority update (such as a security fix). In this case, the update can be forcefully deployed to clients.

In the Enterprise, you can force an update via group policy.

How can I roll back an update to a previous version?

You can't roll back a Windows Store app to a previous version of the app. Because the app package data is removed from the operating system shortly after the package is uninstalled, there is no way to restore it.

Can I move my %ProgramFiles%, %ProgramData% or %UserProfile% directories around?

This is not a supported scenario for Windows Store apps and will cause errors in using the app.

Packaging and deployment programming interfaces

Windows Runtime

• Windows.ApplicationModel.Package class
• Windows.Management.Core namespace
• Windows.Management.Deployment namespace

Win32/COM

• App packaging API
• Package management API

Build date: 11/27/2012