URI のアクティブ化を処理する

Uri (Uniform Resource Identifier) スキーム名の既定のハンドラーになるようにアプリを登録する方法について説明します。 WinUI アプリは、URI スキーム名の既定のハンドラーとして登録できます。 ユーザーが URI スキーム名の既定のハンドラーとしてアプリを選択した場合、その種類の URI が起動されるたびにアプリがアクティブになります。

URI スキーム名には、その種類の URI スキームのすべての URI 起動を処理する場合にのみ登録することをお勧めします。 URI スキーム名に登録する場合は、その URI スキームに対してアプリがアクティブ化されるときに想定される機能をエンド ユーザーに提供する必要があります。 たとえば、mailto: URI スキーム名に登録するアプリは、ユーザーが新しい電子メールを作成できるように、新しい電子メール メッセージを開く必要があります。 URI の関連付けの詳細については、「 ファイル、フォルダー、ライブラリ」を参照してください。

これらの手順では、カスタム URI スキーム名 alsdk://を登録する方法と、ユーザーが alsdk:// URI を起動した際にアプリをアクティブ化する方法を示します。

重要な API

このトピックでは、次の API を使用します。

• Windows.ApplicationModel.Activation.ProtocolActivatedEventArgs
• Windows.UI.Xaml.Application.OnActivated
• AppInstance.GetActivatedEventArgs

手順 1: パッケージ マニフェストで拡張ポイントを指定する

アプリは、パッケージ マニフェストに一覧表示されている URI スキーム名に対してのみアクティブ化イベントを受け取ります。 アプリが alsdk URI スキーム名を処理することを示す方法を次に示します。

1. ソリューション エクスプローラーので、package.appxmanifest をダブルクリックしてマニフェスト デザイナーを開きます。 [宣言] タブを選択して、[利用可能な宣言] ドロップダウンから [プロトコル] を選択し、[追加] をクリックします。

   プロトコルのマニフェスト デザイナーに入力できる各フィールドの簡単な説明を次に示します (詳細については、 AppX パッケージ マニフェスト を参照してください)。

2. images\Icon.pngとして「」と入力します。

3. SDK Sample URI Scheme として「」と入力します

4. alsdkとして「」を入力します。

5. 変更を package.appxmanifest に保存するには、Ctrl キーを押しながら S キーを押します。

   これにより、このような Extension 要素がパッケージ マニフェストに追加されます。 windows.protocol カテゴリは、アプリがalsdk URI スキーム名を処理することを示します。

    <Applications>
        <Application Id= ... >
            <Extensions>
                <uap:Extension Category="windows.protocol">
                  <uap:Protocol Name="alsdk">
                    <uap:Logo>images\icon.png</uap:Logo>
                    <uap:DisplayName>SDK Sample URI Scheme</uap:DisplayName>
                  </uap:Protocol>
                </uap:Extension>
          </Extensions>
          ...
        </Application>
   </Applications>

手順 2: 適切なアイコンを追加する

URI スキーム名の既定値となるアプリのアイコンは、[既定のプログラム] コントロール パネルなど、システム全体のさまざまな場所に表示されます。 この目的のために、プロジェクトに 44 x 44 アイコンを含めます。 アプリタイルのロゴの外観に合わせて、アイコンを透明にするのではなく、アプリの背景色を使用します。 余白を埋め込まずに、ロゴをエッジまで拡張します。 白い背景でアイコンをテストします。 アイコンの詳細については、「 アプリのアイコンとロゴ 」を参照してください。

手順 3: アクティブ化されたイベントを処理する

UWP アプリでは、 OnActivated イベント ハンドラーはすべてのアクティブ化イベントを受け取ります。 Kind プロパティは、アクティブ化イベントの種類を示します。 この例は、 プロトコル のアクティブ化イベントを処理するように設定されています。

public partial class App
{
   protected override void OnActivated(IActivatedEventArgs args)
  {
      if (args.Kind == ActivationKind.Protocol)
      {
         ProtocolActivatedEventArgs eventArgs = args as ProtocolActivatedEventArgs;
         // TODO: Handle URI activation
         // The received URI is eventArgs.Uri.AbsoluteUri
      }
   }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs const& args)
{
    if (args.Kind() == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
    {
        auto protocolActivatedEventArgs{ args.as<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs>() };
        // TODO: Handle URI activation  
        auto receivedURI{ protocolActivatedEventArgs.Uri().RawUri() };
    }
}

void App::OnActivated(Windows::ApplicationModel::Activation::IActivatedEventArgs^ args)
{
   if (args->Kind == Windows::ApplicationModel::Activation::ActivationKind::Protocol)
   {
      Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^ eventArgs =
          dynamic_cast<Windows::ApplicationModel::Activation::ProtocolActivatedEventArgs^>(args);
      
      // TODO: Handle URI activation  
      // The received URI is eventArgs->Uri->RawUri
   }
}

次のコードは、URI を使用してプログラムによってアプリを起動します。

   // Launch the URI
   var uri = new Uri("alsdk:");
   var success = await Windows.System.Launcher.LaunchUriAsync(uri)

URI を使用してアプリを起動する方法の詳細については、「URI の 既定のアプリを起動する」を参照してください。

アプリでは、新しいページを開くアクティブ化イベントごとに新しい XAML フレーム を作成することをお勧めします。 これにより、新しい XAML フレーム のナビゲーション バックスタックには、中断されたときにアプリが現在のウィンドウに存在する可能性がある以前のコンテンツは含まれません。 起動とファイル コントラクトに 1 つの XAML フレーム を使用することを決定したアプリは、新しいページに移動する前に 、フレーム ナビゲーション ジャーナルのページをクリアする必要があります。

プロトコルのアクティブ化を使用して起動する場合、アプリでは、ユーザーがアプリのトップ ページに戻る UI を含める必要があります。

注釈

任意のアプリや Web サイトが、悪意のあるものを含む URI スキーム名を使用することができます。 そのため、URI で取得したデータは、信頼されていないソースから取得される可能性があります。 URI で受け取るパラメーターに基づいて永続的なアクションを実行することはお勧めしません。 たとえば、URI パラメーターを使用してユーザーのアカウント ページにアプリを起動できますが、ユーザーのアカウントを直接変更するために使用することはお勧めしません。

アプリでは、新しい URI ターゲットを開くアクティブ化イベントごとに新しい XAML フレーム を作成することをお勧めします。 これにより、新しい XAML フレーム のナビゲーション バックスタックには、中断されたときにアプリが現在のウィンドウに存在する可能性がある以前のコンテンツは含まれません。

アプリで起動とプロトコル コントラクトに 1 つの XAML フレーム を使用する場合は、新しいページに移動する前に 、フレーム ナビゲーション ジャーナルのページをクリアします。 プロトコル コントラクトを使用して起動する場合は、ユーザーがアプリの先頭に戻る UI をアプリに含める方法を検討してください。

関連コンテンツ

• アソシエーション UWP の起動サンプル
• 既定のプログラム
• ファイルのアクティブ化 を処理する