MSIX Introduction: A comprehensive 24-chapter guide

Get a quick 5,000 words introduction that will bring you up to speed with the latest packaging and deployment technology for Windows.

1. What is MSIX?

MSIX is a new universal package format designed for Windows 10 apps that supports desktop, mobile, and other Windows 10 devices.

In 2018, Microsoft presented MSIX as an improved version of the AppX package (initially used only for UWP apps). MSIX includes valuable knowledge directly from packaging technologies such as MSI, App-V packages, and the Desktop Bridge program.

When it comes to its structure, an MSIX package is very similar to an AppX or App-V package. It is basically a zip package that contains your application files and some XML configuration files.

MSIX offers extended support for Win32 applications, i.e., the standard desktop applications that we’ve used for years. This differentiating factor allows packages to leverage all the new advantages and APIs accessible to an MSIX container when packaging and publishing a normal desktop application.

However, there are some limitations to packaging a desktop application as an MSIX package. These limitations are imposed by Microsoft to ensure the security of the new packaging model as they promised us. Check this article to make sure your application meets the requirements for a successful MSIX migration.

Interesting fact: Advanced Installer is the first application packaging tool to support MSIX technology and was Microsoft's partner for MSIX released in 2018.

Take advantage of Advanced Installer's unmatched capabilities enabled for MSIX with our 30-day, full-featured free trial (no credit card required).

MSIX enables developers to provide a native auto-updates experience without integrating third-party updater tools or publishing in the Microsoft Store, guaranteed security for their end-users, and target a large user base by reaching clients using Windows 10 S and Windows 11 S.

MSIX enables enterprises to stay current and ensure their applications are always up to date. It allows IT Pros and developers to deliver a user-centric solution while still reducing the cost of ownership of the application by reducing the need to repackage and network bandwidth usage.

2. MSIX Container

The MSIX container brings the support from Desktop Bridge and UWP apps together in one, as depicted in the image below.

MSIX Container

As expected, classic Win32 applications packaged as an MSIX will still run only on desktop devices. So, these apps do not “become“ universal simply because we are now packaging them in a new format.

All of these converted apps are still x86 and x64 bit apps, and they cannot run on tablets/phones or other devices with one exception: Always-Connected-PC devices. Win32 apps run on ARM devices with emulation support included in the OS and in specific ARM CPUs.

Just as full UWP apps, Win32 converted apps ( packaged as MSIX) can access the UWP APIs. However, you will only have access to desktop APIs from a Win32 app and you will not have the option to access different APIs (Mobile, Xbox, HoloLens, etc...) as you would with full UWP apps.

You can publish Win32 converted apps to the Microsoft Store, but only target the devices mentioned above.

The MSIX container will provide access to the new Windows 10 and Windows 11 features, which include enhanced security and access to new UWP APIs. But, it will also impose some limitations.

Find a complete list of Microsoft’s recommendations and limitations in the following article: Prepare to package an app (Desktop Bridge).

Below, there's a diagram showing the supported OS resources (of a Win32 application) that an MSIX package can install. On top of this, you can migrate and extend your application to use the new UWP components (app services, background tasks, etc...) to better integrate with the OS or other applications.

MSIX Environment

If you're looking for drivers, note that these are not supported in MSIX packages. Microsoft recommends that all drivers are uploaded to the Microsoft Store by the hardware providers, so the OS manages their installation automatically for the end-user. As MSIX is still in development, we can expect changes, but until then you can still use the hybrid solution adopted by App-V folks, where drivers got deployed with our old friend, the MSI package.

3. Building MSIX Packages

There are multiple tools that can help you build and maintain your MSIX packages. A full list of tools is available in the Microsoft documentation.

Before choosing a tool, you need to understand that there are two main workflows to create an MSIX package:

  1. Create an MSIX from scratch if you have the binaries of your application. This is mostly the case for software vendors, but sometimes even in-house enterprise software might fit this scenario.
  2. Convert anyMSI, EXE, or App-V format package to MSIX. This is usually part of the workflow used by IT pros, not recommended for developers building their own software.

Advanced Installer fully supports building an MSIX either from scratch or by converting your old installer to a new project to be maintained.

Check out the video below to see how to build MSIX and MSI packages from a single project.

Microsoft provides its own tool for converting old installers without generating a project, the MSIX Packaging Tool.

If you are a Visual Studio user, you can use the free Advanced Installer extension to build your MSIX package or the Windows Application Package Project template.

You can also manually build a package by using the MakeAppx.exe command-line utility.

4. Install Location

All MSIX packages are installed/extracted by the OS in the following folder:

%ProgramFiles%\WindowsApps

This is a system location that Windows Explorer does not have access to by default.

Inside the system location folder, you will find subfolders for each app installed on the machine, including OS built-in apps. All the folder names follow this pattern:

PublisherName.AppName_AppVersion_architecture_hash

Here’s an example of a folder name:

Microsoft.WindowsCalculator_10.1806.1821.0_x64_8wekyb3d8bbwe

The extracted MSIX package is inside the folder, just as it would be if we use 7-Zip or similar tools.

Only the OS can write in this location when installing your app. If your app is writing log files or other data inside the installation folder, it will crash.

You need to either update your code to write to %AppData% or use the Package Support Framework to fix it if you don’t have access to the code.

5. Uninstall Cleanup

When you uninstall an MSI package, the application files from AppData and the registry entries that the app made during its lifespan are frequently left on the machine, polluting the system with “garbage.”

On the other hand, MSIX packages simplify the install and uninstall process by reducing machine clutter.

Due to its containerized model, uninstalling an MSIX package will also remove any files the app created while running (under its AppData folder) from the system. This includes all the app files installed under %ProgramFiles%WindowsApps.

The same thing will happen with the registries created by the app. This helps to keep a clean machine state and avoid the all known Windows Rot (aka Registry Rot).

Keep in mind that if the app also creates files in other folders on the machine (Desktop or Downloads folder, for example), those files will not be deleted upon uninstall.

6. File Redirections

Apps installed through MSIX packages run in a sandbox environment (i.e. the container), meaning the OS redirects most of the files and registry operations.

When it comes to file access, the redirection kicks in automatically when you are trying to access files from your package’s VFS ( Virtual File System) and AppData folders.

As we mentioned above, the installation folder is read-only for MSIX-packaged applications. This means that your application can no longer write any files in the install folder.

If your application is still under development, you need to update your code and use AppData or ProgramData as storage options. If you don’t have access to the source code, you can still fix the application using the Package Support Framework (see chapter 13).

For AppData, Windows automatically remaps the known path C:\Users\<username>\AppData\Roaming\ to a path that looks like this:

AppData\Local\Packages\<AppName>.AppData_<GUID>\LocalCache\Roaming\

Handling your AppData from the old code will work by default. The folder remapping is transparent, as long as you are using the recommended Windows APIs to retrieve the AppData folder path. (hardcoded paths are bad and will crash your app).

For debugging purposes, it is useful to know about the folder above, where the OS redirects your app.

NoteThe MSIX container redirects access to its install and AppData folders, this means that you can no longer use the AppData folder to share information with other apps, because those apps will not have access to it. The access is limited to each app’s container.

Recommended API calls for retrieving your AppData folder paths:

//local app data
string localPath = Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData);
//roaming app data
string roamingPath = Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);

7. Win32 Services

Starting with Windows 10 2004, you can deploy an NT Service using an MSIX package.

Even if MSIX packages are only installed (registered) per user, the service installed by an MSIX package will install per machine, just like an MSI.

This means that installing an MSIX containing a service will require administrator credentials.

When you install a service, you can customize the following parameters:

  • Name
  • StartAccount
  • StartType
  • Arguments

Check the following article for a detailed guide on how to install Windows Services with an MSIX package.

8. Registry Redirections

All registry operations are redirected into special per-app registry hives. Your package can contain the following hives, visible in separate files if you extract its contents:

  • Registry.dat
  • User.dat
  • User.Classes.dat

All the HKLM entries will be stored under the Registry.dat file, while the per-user registry entries will be stored in the corresponding hives.

At runtime, all of these hives are virtually merged with the OS registry, allowing the app to “see” the full registry as a singular unit.

The HKLM registry is mostly read-only, and write operations to the user hives are routed to a per-app location, similar to how AppData files are redirected.

The call will be redirected by the OS the first time your app writes to one of these registry hives. The following directory will be used to save the .dat file:

%localappdata%\Packages<APPID>\SystemAppData\Helium

This allows the system to easily delete all the registry used/created by the app throughout its lifespan when it is uninstalled. This -- avoids the all-too-familiar registry rot that has been slowing down Windows machines for decades.

If you want to inspect the registry “visible” to your application, you need to open regedit.exe inside the container of your package. You can do that using the free tool Hover.

9. Digital Signing

All MSIX packages must be digitally signed - no exception.

Security breaches are taking down entire companies and Microsoft decided to help tackle these attacks by enforcing digital signing for all MSIX packages - no matter if the packages install from the Microsoft Store or are sideloaded internally inside your company.

There are two ways to sign a package:

  1. Microsoft Store: If you, as a software vendor, publish the package in the Microsoft Store, you don’t need to sign it. Microsoft will sign the package once they approve your app.
  2. Code Signing Certificate: If you publish the MSIX package for direct download on your website or simply plan to redistribute it internally in your company, you need to sign it with a valid code signing certificate.

For internal company apps, you can even use a self-signed certificate. Make sure that your certificate is also installed on the machines where you plan to deploy your MSIX, otherwise those machines will not recognize the certificate and the MSIX deployment will fail.

The certificate should be located under the “Local Machine -> Trusted Root Certification Authorities” certificates store.

To sign a package, you need the Windows SDK. Inside the SDK you can find the command-line utility that Microsoft recommends for digitally signing: SignTool.exe.

Most packaging tools integrate SignTool automatically, so enabling digital signing is only a simple setting in their GUI.

ImportantThe SHA256 hash algorithm is mandatory for digitally signing MSIX packages, SHA1 is not considered as "valid" by the OS.

10. Package Content Layout

Contents of an extracted MSIX package

The above image lays out the most common MSIX package layout. You can see these resources if you extract the package using makeappx.exe or tools like 7-zip.

Assets - As the name implies, this is where all the app’s graphics assets should be found.

VFS - This folder normally contains the app’s binaries, DLLs, EXEs, config files. Read this article for more details. The VFS and Assets folder are also known as the app payload.

Registry.dat - This file stores the HKLM registry entries of the app. Some packages also have per-user registry entries, in the corresponding files, i.e., User.dat and User.Classes.dat. Read more.

Resources.pri - This file contains app resources, like localized strings and paths for additional resource files. Packages contain one file per language. Read more.

AppxManifest.xml - This XML file is the main resource from the package, as we will detail in the following chapter. It contains all the information required by the system to identify, install, and run the application.

AppxBlockMap.xml - This is an automatically generated file that contains a list of all the app’s binaries and their hashes. It is used by the system for integrity checks and when performing differential updates (e.g. lowering bandwidth usage by downloading only the changes files).

AppxSignature.p7x - This file stores the digital signature information for the package contents.

[Content_Types].xml - This contains information about the types of content in an MSIX package used by the system at install time.

11. AppxManifest.xml

This XML file is the package manifest that must be present in any package. It contains information defining the application, its features, and OS integrations. All this information is used by the system to install/uninstall, update and control the app’s behavior during its lifetime.

The tool that creates the MSIX package, whether it's Visual Studio, Advanced Installer, or any other, generates this file automatically. You can also create it manually, but it is not recommended. This file ends up in the installation folder of your app and it is read-only.

The contents of the file must follow the schemas imposed by the OS, as documented here.

The schemas may differ between major Windows 10 & 11 updates, therefore it is very important to know what OS versions you’re targeting with your app, otherwise, you might end up using Windows features that are not available for all your users.

Take advantage of Advanced Installer's unmatched capabilities enabled for MSIX with our 30-day, full-featured free trial (no credit card required).

12. Package Support Framework (aka PSF)

The Package Support Framework (PSF) is Microsoft’s solution for enterprise customers that need to solve compatibility problems for old desktop applications and don’t have access to the source code.

PSF brings support for API redirection and hooking. So, with PSF you can fix an app that failed to write a file in the installation folder (which is not allowed with MSIX) and redirect it to a recommended location, or update the app’s working directory.

The way it works is quite simple. Microsoft provides an app launcher, a runtime manager DLL, some runtime fixes, and a config.json file. You can also build your own fixes following their documentation.

Their launcher (executable) will become the main app in your package, loading the runtime manager DLL and the fixes. Upon launch, this executable will automatically launch your app, but it will also load the runtime DLL and the fixes into your app, as specified in the config.json file.

This way, when the app is trying to access a resource that is no longer available, for example, write in its installation folder, the runtime fixes will kick in and redirect the call. In our example, it redirects it to a new location under AppData.

How PSF works

To learn more about the Packaging Support Framework, watch our latest webinar:

13. Modification Packages

Practically, this package type is the equivalent of MST files (MSI transforms) from the old days. However, a modification package is not directly tied to a certain version of your main app, this means you can update the main app and still use the old modification package.

Using tools like Advanced Installer or the MSIX Packaging Tool, IT folks from enterprises can customize the MSIX packages they receive from ISVs or generated from older installers and prepare them for mass deployment.

A modification package has the same file extension as an MSIX package, but with slightly different content. The major differences are found in the AppXManifest.xml file. Keep in mind that it must have the same signature (CN) as the target package, or it will fail to install.

A modification package cannot define app entries inside its manifest, it can only add new binaries to the main/target package, and new registry entries.

Modification packages are not directly listed in the “Apps and Features” section. You can find them if you access the “Advanced options” link for the target app.

The following article provides a deep dive on MSIX modification packages, with examples and a video tutorial.

14. MSIX Shared Containers

Shared Containers allow MSIX-packaged applications to share their files and registries. They do so by enabling classic Win32 apps to communicate with each other without changing any code.

If you have worked with App-V, the shared containers offer similar support to the one offered by connection groups for App-V packaged apps.

Defining a shared container is as simple as writing an XML file. This is an example of its structure:

<?xml version="1.0" encoding="utf-8"?>
<AppSharedPackageContainer Name="ContosoContainer">
<PackageFamily Name="Caphyon.WithoutImage_r21n0w1rc5s2y" />
<PackageFamily Name="Caphyon.TheImage_r21n0w1rc5s2y" />
</AppSharedPackageContainer>

Once you have written the XML, you need to deploy it using the dedicated PowerShell commandlets:

  • Add-AppSharedPackageContainer <path>
  • Remove-AppSharedPackageContainer -Name <name>
  • Get-AppSharedPackageContainer -Name <name>
  • Reset-AppSharedPackageContainer -Name <name>

You can even deploy a shared container configuration on a device before the actual applications from the container are deployed. The system will simply ignore it if the complete list of apps from the container is not deployed on the same machine.

For more details and examples, check out this detailed introduction guide to MSIX Shared Containers.

15. Store Publishing

To publish an app in the Microsoft Store follow these steps:

1. You need to register for a Microsoft developer account, either as an individual or as a company.

2. Then, you will set your app's name. Microsoft will check if the name is available and in case it isn't, it will prompt you to choose a different name.

3. Once you've gone through the previous steps, you can submit it to the store.

TipBefore submitting it, we recommend using the Windows App Compatibility Kit (WACK) to validate that your app meets Microsoft’s requirements. If your app passes all the checks, it’s ready for the store.

4. If you’re using Advanced Installer, this validation is one-click away, just go to File -> Settings -> Package Validation” and enable WACK validations.

The first time you publish an application in the Microsoft Store, you could find the experience a little bit intimidating and confusing. We compiled a guide on how to publish your application in the Microsoft Store. We hope it helps!

16. Sideloading

MSIX packages can be installed from the Microsoft Store or by directly installing the package (sideloading, i.e. manual or scripted installation) on the machine.

There are two major conditions that need to be met for a package to be successfully sideloaded:

  • Sideloading must be enabled on the machine. To enable it, use an enterprise policy or through the Setting app.
  • The MSIX package must be digitally signed with a certificate recognized by the machine. As mentioned in the Digital Signatures section, the code-signing certificate can be self-signed or purchased from an authorized issuer.

Once these conditions are met, you can install the MSIX package. You can do so either by double-clicking the MSIX file or using the MSIX PowerShell cmdlet Add-AppxPackage.

This feature means that software vendors are not forced to distribute their apps only through the Microsoft Store. Based on their business strategy, they can publish the MSIX package directly for download on their website and allow users to download and install it manually.

Even if software suppliers publish an update package on their servers, the system's auto-update functionality for modern apps will continue to work for sideloaded apps. Read the Auto-updates section for more details.

17. Auto-updates

The deployment of Updates is a daunting and time-consuming task, albeit still necessary.

This task is drastically simplified with MSIX packages. Especially if you choose to publish your app in the store since the OS will take care of them for you.

For sideloaded apps, you can publish the updated package on your website along with an App Installer file.

Find the contents of a sample .appinstaller file below:

<?xml version="1.0" encoding="utf-8"?>
<AppInstaller Uri="https://uwpupdate.azurewebsites.net/DesktopBridge.Package.appinstaller" Version="1.0.0.0" xmlns="http://schemas.microsoft.com/appx/appinstaller/2017/2">
  <MainBundle Name="c6c08364-cbe5-4267-ae81-ce9be33ff652" Version="1.0.0.0" Publisher="CN=mpagani" Uri="https://uwpupdate.azurewebsites.net/DesktopBridge.Package_1.0.0.0_Test/DesktopBridge.Package_1.0.0.0_x86_x64.appxbundle" />
  <UpdateSettings>
    <OnLaunch HoursBetweenUpdateChecks="0" />
  </UpdateSettings>
</AppInstaller>

All you need to do is to specify in the main app the URL or the UNC path of the file share where you are going to deploy your .appinstaller file and your package. With Advanced Installer and Visual Studio, this is usually specified in the GUI of the application you’re using to build the MSIX package.

If you have even more complex scenarios for checking and downloading application updates -- consider including an auto-updater tool next to your app.

18. App Installer (GUI)

With AppX packages --the predecessor of MSIX-- it wasn't always possible to install a package with just a double-click. The only way to manually install or sideload an app on the machine was using a PowerShell cmdlet: Add-AppXPackage.

Starting in 2018, a GUI was introduced by Microsoft to simplify the manual installation of MSIX packages.

MSIX Install GUI

Unlike the old MSI packages, this GUI is not customizable from inside the package. This means that you cannot display a custom installation dialog to your customers or request user input during the installation.

Microsoft recommends for the app configuration to take place when the users first launch it, as we will discuss in our next chapter: First Launch Configurations.

19. First Launch Configurations

With the introduction of AppX packages, back in Windows 8, Microsoft released new guidelines for application configuration.

For all the apps installed through an AppX or MSIX package, the user configurations take place the first time the app is launched by the user.

  • Because of that, you can't customize the installation UI to gather user input or execute a code to prepare the app before the first launch.
  • Microsoft recommends for this to be done from inside your app, decoupling the install phase from the initial configuration of the app.

In an enterprise deployment, end-users usually expect their apps to be pre-configured and ready to work with. IT departments can use modification packages to include the additional configurations required (eg. a license file, etc.) next to the app.

20. Localization

The Resource Management System helps the user to build the Package Resource Index ( PRI files). The PRI file is a table of named resources and references to the resource file inside the app package. There is one PRI file per language included in each MSIX package.

You can build a multilingual MSIX package with Advanced Installer or Visual Studio. Depending on the tool you use, this file will be built automatically, based on your project configuration.

You can also create the PRI files manually. To do so, you need to read more about Microsoft’s resources naming conventions.

At install time, the system will automatically download the resources it needs depending on the user’s location and not the entire MSIX package (which also contains the resources for all the other supported languages).

Image source: MSDN Blogs

21. App Capabilities

With modern apps, you must request permissions from inside the package manifest for any OS resources that your app tries to access:

  • user pictures,
  • internet connection,
  • devices, like the camera, microphone.

These are your app capabilities. If you don't declare them in your package, the app will fail to load the corresponding UWP APIs -- causing it not to work as expected.

NoteYou can define your app’s capabilities within Advanced Installer’s GUI, by selecting them from the predefined list in the Capabilities view, or its equivalent in your Visual Studio project.

Only full UWP apps or UWP components from within your app, such as a background task or an app service, require defining application capabilities.

Legacy (Win32) code will still continue to run correctly even without the capabilities declared in the package, as it does not use any modern APIs to access those resources.

The only capability required by all Win32 apps is the “Full Trust” option -- which is essential for any Win32 application packaged inside an MSIX.

22. Debugging Inside the MSIX Container

Debugging your code inside an MSIX container is slightly different from the standard debugging in Visual Studio.

  • Generally, when you debug your desktop application in Visual Studio, the app does not run inside a container.
  • Instead, Visual Studio launches the main executable of your app as a simple file from disk.
  • This means that it is not aware of the limitations imposed by an MSIX container.
  • And, it is not able to access the new modern APIs available in the MSIX container.
  • This entire access is practically dependent on the AppXManifest.xml file and the duplication of the VFS folder.

When debugging an MSIX packaged app with Visual Studio, what happens is that Visual Studio builds the MSIX package, either using Advanced Installer’s extension or using its built-in support. Then, the app is installed on the machine and the package is extracted into a temporary location.

Once the app is launched by the debugger, Visual Studio attaches it to its process and you can proceed to debug it, just as you did in the past. The difference is that this time, the process being debugged is running inside the MSIX container.

If you want to "manually debug" your application after it was installed by the MSIX package (for example, to search for files or the registry), you must initiate the appropriate process (explorer.exe, cmd.exe, or regedit.exe) inside the MSIX container.

To do that you can use the free MSIX container debugger tool: Hover.

23. Per User Deployment

By default, apps deployed on the machine are registered per-user, even if they all are installed under the %ProgramFiles%\WindowsApps folder. This could lead us to think that the app is visible to all users from the machine when it's not -- as it was the case for Win32 apps.

Under an account, every user will see only the apps registered to her/his credentials. So, if another user installs a new app on the machine, it will be hidden for all other users.

If two or more users install the same app version on the machine, the application is not downloaded or installed twice. Alternatively, the same source is used to serve the app to both users by registering the app with their respective accounts. This way, the OS reduces disk waste and bandwidth usage when updating the app.

Bandwidth usage MSI vs MSIX

Per-machine deployment can be done by provisioning your package on an operating system from a local computer or on a mounted Windows image before the user accounts are created.

We can do this with the Add-AppxProvisionedPackage cmdlet, for .appx and .msix packages. You can read more in this article about per-machine deployment.

24. Windows 10 S Mode

Windows 10 S mode makes the OS work exclusively with apps from the Microsoft Store.

For a one-time price of $49, the system in S mode can be upgraded to the Professional edition, unlocking the ability to install software from any source, including the old installers (EXE, MSI, etc...).

NoteThis is a one-way operation, going back to S mode is no longer possible after the upgrade.

Devices shipped with Windows 10 S mode seem to be Microsoft’s answer to Google’s Chromebook, which is wildly popular among educational users. These devices are affordable machines that run a fully-fledged version of Windows 10. However, you have to include some improvements (e.g. to make it run better on low specs). Still, with these improvements, some limitations come along.

To enable the installation of the MSIX packages on the above machines, you first need to publish them on the Microsoft Store.

We recommend you to use either the Visual Studio, MSIX Publishing Tool, or Advanced Installer to create the MSIX packages.

The Windows 10 S mode is not like the Windows RT version Microsoft launched with Windows 8.

The Windows RT devices were using ARM processors, thus not being able to run x86 compiled apps. The current devices shipped with Windows 10 S mode come with x86 based CPUs.

There is one exception, the new line of Always-Connected-PC devices, that will still be running on ARM. However, this new generation of ARM can emulate the x86 instructions set, so your desktop apps will still run, but with some limitations.

Addressing MSIX Common Errors

As with any new technology, there will be bumps along the way.

We documented some of the issues we’ve encountered so far.

Check out the FAQ list for MSIX(APPX) packaged apps for error explanations if you have any doubts.

We also wrote a small article that explains how the MSIX Troubleshooter works and how we plan to improve it. Please email us at support at advancedinstaller dot com your feedback, it will help us build a better tool for the community.

To keep yourself updated on the packaging industry, subscribe to Advanced Installer’s weekly brief.

Comments: