透過應用程式安裝程式將安裝參數傳遞至您的應用程式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. 如需詳細資訊,請參閱這 篇 blog 文章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 封裝專案,也可以使用預設的資訊清單編輯器來定義自訂通訊協定,方法是按兩下 package.appxmanifest 檔案,流覽至 [宣告] 索引標籤,然後選取 [可用 的宣告]下的 [ 通訊協定]: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:

Package. package.appxmanifest 中的通訊協定宣告

當您的應用程式在安裝後啟動時,撰寫程式碼來處理參數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. 叫用應用程式安裝程式的 ms 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 中,我已定義自訂通訊協定- 自訂通訊協定、參數 my 參數 ,並將其值指定為 my-param 值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-param-valueWhen 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