アプリインストーラーを使用してインストールパラメーターをアプリに渡す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. これは、ソースやダウンロードの種類などに基づいてさまざまなインストールを追跡または処理し、web のダウンロードに使用する場合や、ユーザーが電子メールキャンペーンから 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 パッケージングプロジェクトを使用している場合は、既定のマニフェストエディターを使用してカスタムプロトコルを定義することもできます。そのためには、 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.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. 次のコード例では、 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());

        }
            
}

カスタムアクティブ化プロトコルとパラメーターをインストール uri に追加するAdd 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. アプリのカスタムプロトコルと、アプリの起動時にアプリに渡されるインストールパラメーターを指す一意のパラメーター activationUriThe 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-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. ユーザーが uri をクリックした後にアプリが起動されると、 activationUri の後に uri のクエリ文字列部分が返されます。この場合、この例では、 カスタムプロトコル:? 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