How to Create a Sparse Package

Written by Danut Ghiorghita · May 31st, 2022 · 5min read

A “Sparse” package contains an AppxManifest.xml but, unlike a regular/full package, the manifest can reference files outside its package in a predetermined 'external location’.

That means your Win32 app will still be installed by the MSI/EXE, but you can take advantage of the modern UWP APIs such as BackgroundTasks, Notifications, LiveTiles, Share, and more through the sparse package.

Add the MSIX build to the project.

In your current project that handles the Win32 app installation, you can add another MSIX build to handle the sparse package. Select the Builds view and use the MSIX/APPX Build toolbar button.

ImportantThe sparse package support is available starting with Windows Build 10.0.19000.0. You need to make sure that the target platform minimum version is at least May 2020 when creating a sparse package.

Target Platform Minimum Version

As the MSIX will be inserted into the MSI, it needs to be built before the MSI, you should change the order in the Builds view:

Builds View

Enable Signing

The signing of the MSIX packages is mandatory so they can be installed. Read more about this in the MSIX and Code Signing Certificates: What Developers Must Know and MSIX Digital Signing articles.

In the Digital Signature page, you can sign your application.

Digital Signature

The certificate needs to be trusted on the machine for the MSIX installation to be successful.

Configure the Sparse Package

Allow external execution

For this, select the Package Information view and enable the Allow External Content option:

Allow External Content

This is what allows your package AppxManifest.xml to reference content outside its package, in a specific location on disk.

This way you can continue deploying all your other app artifacts in the locations you do today while taking advantage of the Sparse Package.

Configure the Starting Point

Configure the Starting Point

Make sure that your Win32App is selected as a starting point. Then, follow the below steps:

  • Remove Entry Point and leave its field empty
  • Select the Medium IL as the Trust Level;
  • Select the Win32 App runtime behavior

The TrustLevel=mediumIL and RuntimeBehavior=Win32App attributes are used to declare that the application associated with this Sparse Package will run like a Win32 app, with no registry + filesystem virtualization and other runtime changes.

To make sure the package identity is received from all activation points (like a CreateProcess call) the embedded manifest from your application EXE file must contain matching MSIX entries:

EXE Manifest entry name

Package Option

packageName

Package Information > Package ID

publisher

Package Information > Publisher ID

applicationId

Application Details > ID

If you have Package Validations enabled, Advanced Installer will trigger an error if it detects a mismatch.

Enable UWP resource compatibility check

You should update the build chain of your application EXE to include those values, or you can use the built-in fixes from Advanced Installer to update the manifest.

Advanced Installer’s Built-in Fixes

Enable the Unvirtualized Resources Capability

Select the Capabilities view and enable the Unvirtualized Resourcescapability, otherwise, your application will not have direct access to the files and registry systems.

Enable Unvirtualized Resources

That’s all you have to do from the MSIX side. Now build the sparse package and let’s use it from an MSI package.

Register the Sparse Package

It’s important to note that, unlike a fully packaged application, an app using a Sparse Package + ‘External Location’ is not fully managed by the OS at deployment, runtime, and uninstall. That means we will have to handle the MSIX installation from the MSI, both register and unregister.

We will handle the Sparse Package registration and unregistration through custom actions.

During the Sparse Package registration, we need to specify the install location of the Win32App so that the external location can be set. Also, to avoid an installation error on older OS versions, we should use a proper install condition, like WindowsBuild > 19000.

Add the MSIX package as a temporary file in the MSI files

Select the Files and Folders view and use the add temporary files toolbar option:

Add Temporary Files

You can read more about how Advanced Installer is handling files added as temporary in the Temporary Files Operations article.

Extract MSIX in the Application Folder

To have access to the assets of the application, the content of the MSIX package needs to be extracted in the same location where the application is installed.

We can extract its content using the predefined extract archive support, configured as below:

Extract Archive Configuration

Install the MSIX

To install the MSIX, you can use the predefined InstallAppxPackage from the Custom Actions view:

InstallAppxPackage

Set the condition field to:

WindowsBuild > 19000

Notice that we pass the APPDIR as the command line to the Sparse Package. Basically, the APPDIR contains the path to the installation directory.

Unregister Sparse Package

For this, you can use the predefined UninstallAppxPackage from the Custom Actions view:

UninstallAppxPackage

You can extract information from the package using the Extract from package… option and the package information will be automatically filled.

Leave the rest as they are, the custom action is already configured to run only during the MSI uninstall. That’s it. Your Win32 application will now run with package identity.

Now that we have configured the sparse package we can simply add MSIX app declarations to our Win32 application. Let’s take an example where we’ll add our app as a “Share Target” for image files.

In the Declarations view, you can configure the properties of a Share Target declaration:

Configure Share Target Declaration Properties

Our Win32App is a photo viewer app that can handle .gif, .jpg and .png images. The files that your app can handle should be listed in the supported file types list.

Conclusion

When you install a sparse package, you get a hybrid installation: the modern MSIX UWP part will seamlessly be installed as part of a traditional MSI installation. The MSIX sparse package will provide your application with the new functionality like Share Target, File Explorer Context Menu, Notifications, and so on.

With the Advanced Installer intuitive GUI, built-in functions, and predefined custom actions, you can easily configure your sparse package.

Subscribe to Our Newsletter

Sign up for free and be the first to receive the latest news, videos, exclusive How-Tos, and guides from Advanced Installer.

Comments: