MSIX and the App Installer File

The MSIX package contains the AppXManifest file, which is an XML structured text file that contains information about the package as set by the developer/creator of the package.

An App Installer File is an additional external XML file that contains all the installation settings needed to deploy and manage the application(s) in the package. It typically contains dozens of critical management settings, such as enabling update management - which makes the App Installer file scope to reach beyond application deployment.

The scope of the App Installer File becomes an important piece you need to account for when you begin designing your MSIX package and deployment workflow in some environments. In some cases, software vendors may choose to build website deployments using the MSIX packages and App Installer files. But you may also find this a useful technique to manage updates from within your organization. Deciding to use the App Installer File to help manage updates is a major decision that will impact your overall application management practices.

Before diving into the key components of the App Installer file, we need to mention one technical requirement for the App Installer file to function correctly on end user devices. Currently (end of 2020), the device must have Windows 10 1709 (or newer) installed and have the necessary APIs for reading and modifying App Installer packages.

Once that requirement is out of the way, the first step in working with App Installer files is to choose a code editor that supports XML markup, autocompletion, and autoformatting. A proper code editor will help eliminate hard to catch syntax errors and efficiently focus on the core elements and their attribute values.

Here's an App Installer sample file you can download for easy reference. Alternatively, you can copy sample content from Microsoft’s documentation or start from scratch by creating a new XML file in your code editor with the “.appinstaller” file extension.

It is strongly recommended that you familiarize yourself with the official App Installer XML schema and regularly review the core elements and their attribute definitions because Microsoft changes which core elements are required as well as attribute data types from time to time.

When you create an App Installer file, make sure the standard XML schema declaration is present and you’re good to go.

The first core element you need to include in the App Installer file is the MainPackage element declaration and the schema required attributes listed below.

<MainPackage
    Name="Contoso.MainApp"
    Publisher="CN=Contoso"
    Version="1.0.0.0"
    ProcessorArchitecture="x64"
    Uri=" http://mywebservice.azurewebsites.net/mainapp.msix" />

The URI attribute contains a web accessible link where the application files are stored. If this value is different from the current location of the App Installer file, Windows will attempt to retrieve the latest copy of the application from the URI location.

The URI accepts connections through HTTP, HTTPS, or file schemes. HTTP is generally discouraged on public networks and should be avoided (if possible). Instead, use HTTPS to ensure the trust of your hosting site.

In the next example, the URI attribute contains a file share path.

<MainPackage
    Name="Contoso.MainApp"
    Publisher="CN=Contoso"
    Version="1.0.0.0"
    ProcessorArchitecture="x64"
    Uri="file://server/share/mainapp.msix" />

For new applications, it is a good practice that you use the xmlns and Version attributes listed in the below table. The Version attribute specifies the current application version, so make sure you verify the version value before you deploy.

App Installer file schema attribute details

In situations where you need to distribute an MSIX file, the App Installer file needs to contain a MainBundle element declaration with the details of the MSIX application to install.

The Name and Publisher attributes are both required, and the publisher value must be a valid X500 distinguished name.

If you are using an *.msixbundle or an *.appxbundle, then you must include the MainBundle element to define the settings. The URI for the MainBundle would point to an *.msixbundle or an *.appxbundle for installation.

<MainBundle
    Name="Contoso.MainApp"
    Publisher="CN=Contoso"
    Version="1.0.0.0"
    ProcessorArchitecture="x64"
    Uri=" http://mywebservice.azurewebsites.net/mainapp.msixbundle" />

For deployment scenarios that require more granular control over application deployment, or have additional dependencies to consider, use the OptionalPackages element or, in some instances, the ModificationPackages which will be discussed later.

With OptionalPackages, you can select which portion(s) of an application to install. It's a good idea to experiment with this technique to improve performance for your end users, especially with large applications.

When building your App Installer file, use the OptionalPackages element to describe the dependent application details.

In the following example, the application details are contained in a Package element because these examples are designed for a single MSIX file deployment. For those use cases where you need to deploy multiple MSIX files, use the Bundle element instead.

The attributes of the Package element have the same constraints as the MainBundle element. The URI points to an MSIX file. The example shows an MSIX package as an optional package.

<OptionalPackages>
    <Package
        Name="Contoso.OptionalApp1"
        Publisher="CN=Contoso"
        Version="2.23.12.43"
        Uri=" https://mywebservice.azurewebsites.net />
</OptionalPackages>

The next example uses only an *.msixbundle package as a dependency. As a result, the Bundle element is required instead of the Package element.

<OptionalPackages>
    <Bundle
        Name="Contoso.OptionalApp2"
        Publisher="CN=Contoso"
        Version="1.32.13.63"
        Uri=" http://mywebservice.azurewebsites.net/OptionalApp1.msixbundle" />
</OptionalPackages>

For larger organizations, it is strongly recommended to get to know the ModificationPackages element because it is where you define unique application customizations for the MSIX container that get applied to the application as it is installed.

The ModificationPackages element helps decouple customizations to the MSIX package into a separate package, while still giving admins the ability to fine-tune the application experience for the end user.

In the next example, the URI attribute contains a link to a modification package where the modification files are located.

<ModificationPackages>
    <Package
        Name="Contoso.Customization"
        Publisher="CN=Contoso"
        Version="1.0.0.0"
        Uri=" https://mywebservice.azurewebsites.net/ContosoCustomization.msix" />
</ModificationPackages>

Dependencies, such as Visual C++ runtimes, are defined in the Dependencies element. The next example shows how to use the Dependencies element.

<Dependencies>
    <Package 
        Name="Microsoft.VCLibs.140.00" 
        Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" 
        Version="14.0.24605.0" 
        ProcessorArchitecture="x64"           
        Uri=" http://mywebservice.azurewebsites.net/fwkx64.appx" />
</Dependencies>

The UpdateSettings element defines important parameters that control how updates are managed.

You can control whether updates happen independently from the application launch or only when the user launches the application. You can also choose whether the user is prompted or if the update is silent and happens in the background.

For example, including the AutomaticBackgroundTask element instructs the application to check for updates in the background.

<UpdateSettings>
    <AutomaticBackgroundTask/>
</UpdateSettings>

In the next example, find two useful update settings. First, the OnLaunch element, which forces the application to check for updates each time it is launched by setting the HoursBetweenUpdateChecks attribute to zero.

Next, we need to make sure that the user receives a prompt about the update by setting the ShowPrompt attribute to “true”.

Finally, a typical approach would be to force the user to update the application before it launches by setting the UpdateBlocksActivation attribute to “true”.

Then, you need to include the ForceUpdateFromAnyVersion element to ensure that I can rollback an app’s version in case there’s an issue. Without this setting configured, you can only increase the app’s version.

<UpdateSettings>
    <OnLaunch HoursBetweenUpdateChecks="0" ShowPrompt="true" UpdateBlocksActivation="true" />
    <AutomaticBackgroundTask/>
    <ForceUpdateFromAnyVersion>true</ForceUpdateFromAnyVersion>
</UpdateSettings>

It’s important to have your app team make these decisions ahead of time and document the installation update settings.

The last thing to do with your App Installer file is to make sure you close the AppInstaller element in the file.

</AppInstaller>

And there you have it, make sure to review the complete demo file as a reference, then try making your own App Installer file from scratch.