Passing installation parameters to your app via App Installer

When distributing your app using MSIX you can configure your app such that query string parameters you define in the download/install uri are passed on to your app when it launches, after a user clicks on the download/install uri. This works whether it's the first time a user is installing the app or if the app was previously installed. This article shows how to configure your packaged application and its download/install uri to take advantage of this functionality. This can be useful if you want to track or handle different installs based on the source, download type etc and will work for web downloads, and any other cases where a user clicks the uri e.g. from an email campaign. For more details check out this blog post.

Configure your application for protocol activation

The first thing to do is to register your app for it to be launched using a custom protocol you define. When this protocol is invoked, your application is launched and any prameters specified in the uri are passed to your app's activation event arguments when it is launched. You can register the protocol by adding a protocol extension entry in the Application Extensions node in your MSIX's appxmanifest.xml file:

<Application>
...
   <Extensions>
     <uap:Extension Category="windows.protocol">
        <uap:Protocol Name="my-custom-protocol"/>
     </uap:Extension>
   </Extensions>
  
...
</Application>

If you are using the Windows Packaging Project, you can also define a custom protocol using the default manifest editor by double clicking the package.appxmanifest file, navigating to the Declarations tab and selecting Protocol under Available Declarations:

Write code to handle parameters when your app is launched after installation

You will need to implement code in your application to handle the installation parameters that will be passed to your app when it is launched. The example code below uses the AppInstance.GetActivatedEventArgs method to determine the type of activation used to instantiate an app (you can also handle the parameters using a different method). When your app is launched/activated with query sting parameters from an install uri (see defintion in the next section), the activation type will be a protocol activation as defined by your custom protocol declared in your appxmanifest.xml and download/install uri. The activation event args will be of type ProtocolActivatedEventArgs and that is what the code below uses:

using Windows.ApplicationModel;
using Windows.ApplicationModel.Activation;

public static void Main(string[] cmdArgs)
{
            
    var activationArgs = AppInstance.GetActivatedEventArgs();
    switch (activationArgs.Kind)
    {
        //Install parameters will be passed in during a protocol activation
        case ActivationKind.Protocol:
        HandleProtocolActivation(activationArgs as ProtocolActivatedEventArgs);
        break;
        case ActivationKind.Launch:
        //Regular launch activation type
        HandleLaunch(activationArgs as LaunchActivatedEventArgs);
        break;
        default:
        break;
     }       
    

     static void HandleProtocolActivation(ProtocolActivatedEventArgs args)
     {

         if (args.Uri != null)
        {
            //Handle the installation parameters in the protocol uri
            handleInstallParameter(args.Uri.ToString());

        }
            
}

Add your custom activation protocol and parameters to the installation uri

Once your app is set up to handle your installation parameters, you can customise the app download/install uri to contain uniquely defined parameters that will be passed on to your app at launch, after a user clicks on the uri. The uri must contain:

1. The ms-appinstaller protocol that invokes App Installer.
2. The unique parameter activationUri that points to your app's custom protocol and the install parameters you want passed to your app when it is launched.
3. Your app's custom protocol and the the parameter and its value.

In the example uris below, I have defined a custom protocol my-custom-protocol, a parameter my-parameter and given it the value my-param-value. When the app is launched after a user clicks on the uri, it will receive the query string portion of the uri after activationUri, in this case that will be my-custom-protocol:?my-parameter=my-param-value.

ms-appinstaller:?source=https://contoso.com/myapp.appinstaller&activationUri=my-custom-protocol:?my-parameter=my-param-value

ms-appinstaller:?source=https://contos.com/myapp.msix&activationUri=my-custom-protocol:?my-parameter=my-param-value