Passage des paramètres d’installation à votre application via le programme d’installation de l’applicationPassing installation parameters to your app via App Installer

Quand vous distribuez votre application à l’aide de MSIX, vous pouvez configurer votre application de sorte que les paramètres de chaîne de requête que vous définissez dans l’URI de téléchargement/installation soient transmis à votre application lors de son lancement, après qu’un utilisateur a cliqué sur l’URI de téléchargement/installation.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. Cela fonctionne qu’il s’agit de la première fois qu’un utilisateur installe l’application ou si l’application a déjà été installée.This works whether it's the first time a user is installing the app or if the app was previously installed. Cet article explique comment configurer votre application MSIX empaquetée et son URI de téléchargement/installation pour tirer parti de cette fonctionnalité.This article shows how to configure your MSIX packaged application and its download/install uri to take advantage of this functionality. Cela peut être utile si vous souhaitez suivre ou gérer les différentes installations basées sur la source, le type de téléchargement, etc., ainsi que les téléchargements Web et les autres cas où un utilisateur clique sur l’URI, par exemple, à partir d’une campagne par courrier électronique.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. Pour plus d’informations, consultez ce billet de blog.For more details check out this blog post.

Configurer votre application pour l’activation de protocoleConfigure your application for protocol activation

La première chose à faire est d’inscrire votre application pour qu’elle soit lancée à l’aide d’un protocole personnalisé que vous définissez.The first thing to do is to register your app for it to be launched using a custom protocol you define. Lorsque ce protocole est appelé, votre application est lancée et les prameters spécifiés dans l’URI sont passés aux arguments d’événement d’activation de votre application lorsqu’elle est lancée.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. Vous pouvez inscrire le protocole en ajoutant une entrée d’extension de protocole dans le nœud extensions d’application du fichier appxmanifest.xml de votre MSIX :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>

Si vous utilisez le projet de Packaging Windows, vous pouvez également définir un protocole personnalisé à l’aide de l’éditeur de manifeste par défaut en double-cliquant sur le fichier Package. appxmanifest , en accédant à l’onglet déclarations et en sélectionnant protocole sous déclarations disponibles: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:

Déclaration de protocole dans package. appxmanifest

Écrire du code pour gérer les paramètres lorsque votre application est lancée après l’installationWrite code to handle parameters when your app is launched after installation

Vous devrez implémenter le code dans votre application pour gérer les paramètres d’installation qui seront transmis à votre application lors de son lancement.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. L’exemple de code ci-dessous utilise la méthode AppInstance. GetActivatedEventArgs pour déterminer le type d’activation utilisé pour instancier une application (vous pouvez également gérer les paramètres à l’aide d’une méthode différente).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). Quand votre application est lancée/activée avec des paramètres de type de requête à partir d’un URI d’installation (voir définition dans la section suivante), le type d’activation est une activation de protocole telle que définie par votre protocole personnalisé déclaré dans votre appxmanifest.xml et l’URI de téléchargement/installation.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. Les arguments de l’événement d’activation seront de type ProtocolActivatedEventArgs et celui utilisé par le code ci-dessous :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());

        }
            
}

Ajouter votre protocole et vos paramètres d’activation personnalisés à l’URI d’installationAdd your custom activation protocol and parameters to the installation uri

Une fois que votre application est configurée pour gérer vos paramètres d’installation, vous pouvez personnaliser l’URI du téléchargement/de l’installation de l’application pour qu’elle contienne des paramètres définis de manière unique qui seront transmis à votre application lors du lancement, après qu’un utilisateur a cliqué sur l’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. L’URI doit contenir :The uri must contain:

  1. Protocole MS-appinstaller qui appelle le programme d’installation de l’application.The ms-appinstaller protocol that invokes App Installer.
  2. Le paramètre unique activationUri qui pointe vers le protocole personnalisé de votre application et les paramètres d’installation que vous souhaitez transmettre à votre application lors de son lancement.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. Le protocole personnalisé de votre application et le paramètre et sa valeur.Your app's custom protocol and the the parameter and its value.

Dans les exemples d’URI ci-dessous, j’ai défini un protocole personnalisé My-Custom-Protocol, un paramètre My-Parameter et j’ai donné la valeur My-param-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. Lorsque l’application est lancée après qu’un utilisateur a cliqué sur l’URI, elle reçoit la partie de la chaîne de requête de l’URI après activationUri, dans le cas présent, il s’agit de My-Custom-Protocol :? My-Parameter = 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