URI のアクティブ化の処理

[アーティクル]
07/05/2024

重要な API

URI (Uniform Resource Identifier) スキーム名の既定のハンドラーとしてアプリを登録する方法について説明します。 Windows デスクトップアプリとユニバーサル Windows プラットフォーム (UWP) アプリの両方が、URI スキーム名の既定のハンドラーとして登録できます。ユーザーが URI スキーム名の既定のハンドラーとしてアプリを選択した場合、その種類の URI が起動されるたびにアプリがアクティブになります。

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

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

Note

UWP アプリでは、組み込みのアプリとオペレーティングシステムで使うために、特定の URI とファイル拡張子が予約されています。予約済みの URI またはファイル拡張子でアプリを登録しようとすると無視されます。 UWP アプリ登録できない URI スキームのアルファベット順の一覧については予約済み URI スキームの名前とファイルの種類に関するページを参照してください。これらは予約済みまたは禁止されているためです。

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

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

ソリューションエクスプローラーで package.appxmanifest をダブルクリックしてマニフェストデザイナーを開きます。 Declarations タブを選択し、Available Declarations ドロップダウンで Protocolを選択し、追加をクリックします。

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

フィールド	説明
ロゴ	コントロールパネルの Set Default Programs で URI スキーム名を識別するために使用するロゴを指定します。ロゴが指定されていない場合は、アプリの小さなロゴが使用されます。
表示名	コントロールパネルの Set Default Programs で URI スキーム名を識別する表示名を指定します。
名前	Uri スキームの名前を選択します。
	注名前はすべて小文字である必要があります。
	予約済みのファイルの種類と禁止されているファイルの種類予約済みまたは禁止されているため、UWP アプリに登録できない URI スキームのアルファベット順の一覧については予約済み URI スキームの名前とファイルの種類に関するページを参照してください。
Executable	プロトコルの既定の起動実行可能ファイルを指定します。指定しない場合は、アプリの実行可能ファイルが使用されます。指定する場合は、長さが 1 から 256 文字の文字列で、".exe" で終わっている必要があります。また、>、<、:、"、\|、?、* の文字を含めることはできません。指定した場合は、 Entry ポイントも使用されます。 Entry ポイントが指定されていない場合は、アプリに定義されているエントリポイントが使用されます。
エントリポイント	プロトコル拡張機能を処理するタスクを指定します。これは通常、Windows ランタイム型の完全な名前空間修飾名です。指定しない場合は、アプリのエントリポイントが使用されます。
スタートページ	機能拡張ポイントを処理する Web ページ。
リソースグループ	リソース管理のために拡張機能のアクティブ化をグループ化するために使用できるタグ。
必要なビュー (Windows のみ)	Desired View フィールドを指定して、アプリのウィンドウが URI スキーム名の起動時に必要な領域の量を示します。 Desired View に指定できる値は、Default、UseLess、UseHalf、UseMore、または UseMinimum です。注 Windows では、ターゲットアプリの最終的なウィンドウサイズを決定するときに複数の異なる要素が考慮されます。たとえば、ソースアプリの設定、画面上のアプリの数、画面の向きなどです。 Desired View を設定しても、ターゲットアプリの特定のウィンドウ動作は保証されません。モバイルデバイスファミリ: モバイルデバイスファミリでは、必要なビューはサポートされていません。

Logoとして「images\Icon.png」と入力します。
Display 名として「SDK Sample URI Scheme」と入力します
[名前] として「alsdk」と入力します。
変更を 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: アクティブ化されたイベントを処理する

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

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
      }
   }
}

Protected Overrides Sub OnActivated(ByVal args As Windows.ApplicationModel.Activation.IActivatedEventArgs)
   If args.Kind = ActivationKind.Protocol Then
      ProtocolActivatedEventArgs eventArgs = args As ProtocolActivatedEventArgs
      
      ' TODO: Handle URI activation
      ' The received URI is eventArgs.Uri.AbsoluteUri
 End If
End Sub

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
   }
}

Note

プロトコルコントラクトを介して起動した場合、戻るボタンが使われたときは、アプリの以前のコンテンツに戻るのではなく、アプリを起動した画面に戻るようにする必要があります。

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

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

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

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

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

解説

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

Note

アプリの新しい URI スキーム名を作成する場合は、RFC 4395 のガイダンスに従う必要があります。これにより、名前が URI スキームの標準を満たしていることを確認できます。

Note

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

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

次の方法で共有

URI のアクティブ化の処理

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

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

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

解説

完全なサンプルアプリ

概念

タスク

ガイドライン

リファレンス

フィードバック

その他のリソース

次の方法で共有

URI のアクティブ化の処理

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

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

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

解説

関連トピック

完全なサンプル アプリ

概念

タスク

ガイドライン

リファレンス

フィードバック

その他のリソース

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

完全なサンプルアプリ