通过应用安装程序将安装参数传递到应用程序Passing installation parameters to your app via App Installer

使用 .MSIX 分发应用时,可以配置应用,以便在 "下载/安装 uri" 中定义的查询字符串参数在启动时传递给你的应用,并在用户单击 "下载/安装" uri 后传递给你的应用。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. 本文介绍如何配置 .MSIX 打包应用程序及其下载/安装 uri 以利用此功能。This article shows how to configure your MSIX packaged application and its download/install uri to take advantage of this functionality. 如果你想要基于源、下载类型等跟踪或处理不同的安装,并且在用户单击 uri (如电子邮件活动)时使用的任何其他情况下,这可能很有用。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. 调用此协议时,将启动应用程序,并在启动时将 uri 中指定的任何 prameters 传递给应用的激活事件参数。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. 可以通过在 .MSIX 的 appxmanifest.xml 文件中的 "应用程序扩展" 节点中添加协议扩展条目来注册协议: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>

如果使用的是 Windows 打包项目,还可以通过双击 appxmanifest.xml 文件,在 "声明" 选项卡中导航到 "声明" 选项卡,然后在 "可用声明" 下选择 协议,来定义自定义协议: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:

包中的协议声明。 appxmanifest.xml

当应用程序在安装后启动后,编写代码来处理参数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. 下面的示例代码使用 AppInstance GetActivatedEventArgs 方法来确定用于实例化应用程序的激活类型 (你还可以使用不同的方法) 来处理参数。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). 当你的应用程序通过安装 uri 中的查询字符串参数启动/激活时 (请参阅下一节中的定义) ,激活类型将是你的自定义协议定义的协议激活,该协议是在 appxmanifest.xml 和下载/安装 uri 中声明的。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. 激活事件参数的类型为 ProtocolActivatedEventArgs ,这是以下代码使用的代码: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());

        }
            
}

将自定义激活协议和参数添加到安装 uriAdd your custom activation protocol and parameters to the installation uri

将应用设置为处理安装参数后,可以将应用下载/安装 uri 定制为包含唯一定义的参数,这些参数将在用户单击 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. Uri 必须包含:The uri must contain:

  1. 调用应用安装程序的 appinstaller 协议。The ms-appinstaller protocol that invokes App Installer.
  2. 唯一的参数 activationUri ,它指向你的应用程序的自定义协议,以及你想要在启动时传递给应用程序的安装参数。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.

在下面的示例 uri 中,我定义了自定义协议- 定义协议,参数- 参数,并为 其指定了值-参数 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. 当用户单击 uri 后启动应用程序时,它将在 activationUri 后收到 uri 的查询字符串部分,在这种情况下,将显示 自定义协议:? my-parameter = my-参数-值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