External Location

We talked recently about PackageVolume as one of the ways to stage packages.

Let’s turn our gaze to External Location, which plays a distinct role in MSIX, with similarities to – and important differences from – other options.

Why is External Location?

MSIX deployment provides a full-service software installation stack. The process is simple: collect your content, describe your package in an AppxManifest.xml, and run makeappx.exe and signtool.exe to create a signed .msix to distribution and install.

But…what if you already have a product with an existing installer? What if you need to extend your product with features uniquely requiring MSIX? For example, if your application needs to run with package identity to access resources requiring identity? Or you need to add Share Target support? Or File Explorer context menus in Windows 11?

Before External Location, this meant replacing your existing installer with an MSIX package. This can be costly for some, or simply not possible if MSIX doesn’t support all your deployment needs.

If only an existing installer could incrementally leverage MSIX…

And thus was born External Location.

What is External Location?

A package with an External Location is installed with an additional path, specified at install time. This tells Windows where to find the package’s payload files, separately from its install location.

Example without External Location

For example, create Contoso.PointOfSale-v1.2.3.4-x64.msix using this AppxManifest.xml fragment:

<?xml version="1.0" encoding="utf-8"?>
<Package ...>
  <Identity Name="Contoso.PointOfSale"
            Publisher="CN=Contoso LLC, O=Contoso LLC, L=Paris, C=France"
            Version="1.2.3.4"
            ProcessorArchitecture="x64" />
  ...
  <Applications>
    <Application ... Executable="PointOfSale.exe">
...
</Package>    

Now install the package, e.g.

Add-AppxPackage C:\Packages\Downloads\Contoso.PointOfSale-v1.2.3.4-x64.msix

As a result, Windows stages the package at C:\Program Files\WindowsApps\Contoso.PointOfSale_1.2.3.4_x64__eh4htm4n7tdre, containing AppxManifest.xml, PointOfSale.exe and the rest of the package’s contents.

Windows launches C:\Program Files\WindowsApps\Contoso.PointOfSale_1.2.3.4_x64__eh4htm4n7tdre\PointOfSale.exe when you activate the app.

Example with External Location

Installing a package with an External Location requires adding to AppxManifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<Package ...>
  <Identity Name="Contoso.Invoice"
            Publisher="CN=Contoso LLC, O=Contoso LLC, L=Paris, C=France"
            Version="4.1.2023.0"
            ProcessorArchitecture="x64" />
  <Properties>
    ...
    <uap10:AllowExternalContent>true</uap10:AllowExternalContent>
  </Properties>
  ...
  <Applications>
    <Application ... Executable="Invoice.exe">
...
</Package>    

and an additional path, specified at install time.

Assume your existing installer has placed Invoice.exe and its supporting files in D:\MyApps\Contoso.

Add-AppxPackage C:\Packages\Downloads\Contoso.Invoice-v4.1.2023.0-x64.msix -ExternalLocation D:\MyApps\Contoso

As a result, Windows stages the package at C:\Program Files\WindowsApps\Contoso.Invoice_4.1.2023.0_x64__eh4htm4n7tdre, containing the package’s contents.

But…at runtime, activation uses D:\MyApps\Contoso\Invoice.exe.

Location, Location, Location

A package always has an Install location. This is C:\Program Files\WindowsApps\Contoso.Invoice_4.1.2023.0_x64__eh4htm4n7tdre in the Invoice example above.

A package may also have a per-machine External Location. This is commonly referred to as the Machine External Location.

Also.

The External Location doesn’t replace the install location. Instead, it supplements it.

P.S. A package may also have a per-user External Location, but this is rarer and has its own story and nuances. We’ll discuss this in a future post. For now, assume “External Location” mentioned in this post always means a Machine External Location.

What External Location does

A package’s External Location tells Windows where to find the package’s payload files.

Windows still expects AppxManifest.xml, AppxBlockMap.xml and other Footprint files in the package’s install location, e.g. C:\Program Files\WindowsApps\Contoso.Invoice_4.1.2023.0_x64__eh4htm4n7tdre\AppxManifest.xml.

Windows normally looks for files referenced in AppxManifest.xml at the package’s install location. The magic of External Location is to tell Windows somewhere else to look for those files:

• <Application Executable="Invoice.exe" ...>
• <uap:VisualElements Square44x44Logo="bill.png">
• <desktop10:DataShortcut File="README.txt" ...>
• …

This makes for more of a “Rent, not Buy” scenario. MSIX doesn’t install or manage those files. MSIX doesn’t own them. MSIX isn’t responsible for repairing them. Securing them. Uninstalling them. MSIX merely knows where to find them. Someone else creates, deletes and manages them.

An MSIX package with an External Location supplements some other installer.

That’s why this is sometimes informally referred to as a “Bring Your Own Installer” model.

Not Allowed but Required

<uap10:AllowExternalContent>true</uap10:AllowExternalContent> MUST be declared in AppxManifest.xml to install a package with an External Location.

In addition, a package MUST be installed with an External Location if its manifest sets <uap10:AllowExternalContent>true</uap10:AllowExternalContent>.

The name is a misnomer. It should have been RequireExternalContent.

Another task for when that time machine finally works…