URI のアクティブ化の処理Handle URI activation

重要な APIImportant APIs

URI (Uniform Resource Identifier) スキーム名の既定のハンドラーとしてアプリを登録する方法について説明します。Learn how to register an app to become the default handler for a Uniform Resource Identifier (URI) scheme name. Windows デスクトップ アプリとユニバーサル Windows プラットフォーム (UWP) アプリの両方を、URI スキーム名の既定のハンドラーとして登録できます。Both Windows desktop apps and Universal Windows Platform (UWP) apps can register to be a default handler for a URI scheme name. アプリを URI スキーム名の既定のハンドラーとして選ぶと、アプリはその種類の URI を起動するたびにアクティブ化されます。If the user chooses your app as the default handler for a URI scheme name, your app will be activated every time that type of URI is launched.

URI スキーム名に登録するのは、その種類の URI スキームのすべての URI 起動を処理する場合のみにすることをお勧めします。We recommend that you only register for a URI scheme name if you expect to handle all URI launches for that type of URI scheme. URI スキーム名に登録する場合は、その URI スキームのためにアプリをアクティブ化した際に期待される機能をエンド ユーザーに提供する必要があります。If you do choose to register for a URI scheme name, you must provide the end user with the functionality that is expected when your app is activated for that URI scheme. たとえば、mailto: URI スキーム名に登録したアプリでは、新しいメールを開いて、ユーザーが新しいメールを書くことができるようにする必要があります。For example, an app that registers for the mailto: URI scheme name should open to a new e-mail message so that the user can compose a new e-mail. URI の関連付けについて詳しくは、「ファイルの種類と URI のガイドラインとチェック リスト」をご覧ください。For more info on URI associations, see Guidelines and checklist for file types and URIs.

以下の手順では、カスタムの URI スキーム名 alsdk:// を登録する方法と、ユーザーによって alsdk:// URI が起動されたときにアプリをアクティブ化する方法について説明します。These steps show how to register for a custom URI scheme name, alsdk://, and how to activate your app when the user launches a alsdk:// URI.

注意

、UWP アプリで組み込みのアプリとオペレーティング システムで使用するため、特定の Uri とファイル拡張子が予約されています。In UWP apps, certain URIs and file extensions are reserved for use by built-in apps and the operating system. 予約されている URI またはファイル拡張子にアプリを登録しようとしても無視されます。Attempts to register your app with a reserved URI or file extension will be ignored. 予約または禁止されいるため、UWP アプリを登録できない URI スキームの一覧 (アルファベット順) については、「予約済みの URI スキーム名とファイルの種類」をご覧ください。See Reserved URI scheme names and file types for an alphabetic list of Uri schemes that you can't register for your UWP apps because they are either reserved or forbidden.

ステップ 1: パッケージ マニフェストに拡張点を指定するStep 1: Specify the extension point in the package manifest

アプリは、パッケージ マニフェストに一覧表示される URI スキーム名のアクティブ化イベントだけを受け取ります。The app receives activation events only for the URI scheme names listed in the package manifest. アプリが alsdk URI スキーム名を処理することを示す方法は次のとおりです。Here's how you indicate that your app handles the alsdk URI scheme name.

  1. ソリューション エクスプローラーで、package.appxmanifest をダブルクリックしてマニフェスト デザイナーを開きます。In the Solution Explorer, double-click package.appxmanifest to open the manifest designer. [宣言] タブを選び、[使用可能な宣言] ドロップダウンから [プロトコル] を選んで [追加] をクリックします。Select the Declarations tab and in the Available Declarations drop-down, select Protocol and then click Add.

    プロトコルのマニフェスト デザイナーで指定することができる各フィールドについて、以下で簡単に説明します (詳しくは、「AppX パッケージ マニフェスト」をご覧ください)。Here is a brief description of each of the fields that you may fill in the manifest designer for the Protocol (see AppX Package Manifest for details):

フィールドField 説明Description
ロゴLogo コントロール パネル[既定のプログラムを設定する] で URI スキーム名を識別するために使われるロゴを指定します。Specify the logo that is used to identify the URI scheme name in the Set Default Programs on the Control Panel. ロゴを指定しない場合は、アプリの小さいロゴが使われます。If no Logo is specified, the small logo for the app is used.
表示名Display Name コントロール パネル[既定のプログラムを設定する] で URI スキーム名を識別するための表示名を指定します。Specify the display name to identify the URI scheme name in the Set Default Programs on the Control Panel.
名前Name URI スキームの名前を選びます。Choose a name for the Uri scheme.
名前はすべて小文字である必要があります。Note The Name must be in all lower case letters.
予約および禁止されているファイルの種類 予約または禁止されているため、UWP アプリを登録できない URI スキームの一覧 (アルファベット順) については、予約済みの URI スキーム名とファイルの種類に関するページをご覧ください。Reserved and forbidden file types See Reserved URI scheme names and file types for an alphabetic list of Uri schemes that you can't register for your UWP apps because they are either reserved or forbidden.
実行可能ファイルExecutable プロトコルの既定の起動実行可能ファイルを指定します。Specifies the default launch executable for the protocol. 指定しない場合、アプリの実行可能ファイルが使用されます。If not specified, the app's executable is used. 指定する場合は、長さが 1 ~ 256 文字の文字列で、".exe" で終わっている必要があります。また、>、<、:、"、|、?、* の各文字を含めることはできません。If specified, the string must be between 1 and 256 characters in length, must end with ".exe", and cannot contain these characters: >, <, :, ", |, ?, or *. 指定した場合、エントリ ポイントも使用されます。If specified, the Entry point is also used. [エントリ ポイント] を指定しない場合、アプリで定義されているエントリ ポイントが使用されます。If the Entry point isn't specified, the entry point defined for the app is used.
エントリ ポイントEntry point プロトコル拡張機能を処理するタスクを指定します。Specifies the task that handles the protocol extension. これは、通常、Windows ランタイムの型の完全な名前空間修飾名です。This is normally the fully namespace-qualified name of a Windows Runtime type. 指定しない場合、アプリのエントリ ポイントが使用されます。If not specified, the entry point for the app is used.
スタート ページStart page 拡張ポイントを処理する Web ページです。The web page that handles the extensibility point.
リソース グループResource group リソース管理のために拡張機能のアクティブ化をグループ化するために使用できるタグ。A tag that you can use to group extension activations together for resource management purposes.
必要な表示 (Windows のみ)Desired View (Windows-only) この URI スキーム名に対して起動されたときにアプリのウィンドウに必要なスペースの量を示すには、[必要な表示] フィールドを指定します。Specify the Desired View field to indicate the amount of space the app's window needs when it is launched for the URI scheme name. [必要な表示] に指定できる値は、DefaultUseLessUseHalfUseMore、または UseMinimum です。The possible values for Desired View are Default, UseLess, UseHalf, UseMore, or UseMinimum.
Windows では、ターゲット アプリの最終的なウィンドウ サイズを決定するときに複数の異なる要素が考慮されます。たとえば、ソース アプリの設定、画面上のアプリの数、画面の向きなどです。Note Windows takes into account multiple different factors when determining the target app's final window size, for example, the preference of the source app, the number of apps on screen, the screen orientation, and so on. [必要な表示] を設定しても、ターゲット アプリの特定のウィンドウ動作が保証されるわけではありません。Setting Desired View doesn't guarantee a specific windowing behavior for the target app.
モバイル デバイス ファミリ: [必要な表示] はモバイル デバイス ファミリではサポートされていません。Mobile device family: Desired View isn't supported on the mobile device family.
  1. [ロゴ]images\Icon.png と入力します。Enter images\Icon.png as the Logo.
  2. [表示名]SDK Sample URI Scheme と入力します。Enter SDK Sample URI Scheme as the Display name
  3. [名前]alsdk と入力します。Enter alsdk as the Name.
  4. Ctrl + S キーを押して、変更を package.appxmanifest に保存します。Press Ctrl+S to save the change to package.appxmanifest.

    これにより、次のような Extension 要素がパッケージ マニフェストに追加されます。This adds an Extension element like this one to the package manifest. windows.protocol カテゴリは、アプリが alsdk URI スキーム名を処理することを示しています。The windows.protocol category indicates that the app handles the alsdk URI scheme name.

    <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: 適切なアイコンを追加するStep 2: Add the proper icons

URI スキーム名の既定となるアプリは、そのアイコンがシステムのさまざまな場所に表示されます。アイコンは、[既定のプログラム] コントロール パネルなどに表示されます。Apps that become the default for a URI scheme name have their icons displayed in various places throughout the system such as in the Default programs control panel. このため、プロジェクトに 44 x 44 アイコンを含めます。Include a 44x44 icon with your project for this purpose. アプリのタイルのロゴの外観を調和させ、アイコンを透明にするのではなく、アプリの背景色を使います。Match the look of the app tile logo and use your app's background color rather than making the icon transparent. パディングせずにロゴを端まで拡張します。Have the logo extend to the edge without padding it. アイコンは、白い背景でテストします。Test your icons on white backgrounds. アイコンについて詳しくは、「タイルとアイコン アセットのガイドライン」をご覧ください。See Guidelines for tile and icon assets for more details about icons.

ステップ 3: アクティブ化イベントを処理するStep 3: Handle the activated event

OnActivated イベント ハンドラーは、すべてのファイル アクティブ化イベントを受け取ります。The OnActivated event handler receives all activation events. Kind プロパティは、アクティブ化イベントの種類を示しています。The Kind property indicates the type of activation event. 次の例では、Protocol アクティブ化イベントを処理するように設定されています。This example is set up to handle Protocol activation events.

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

注意

プロトコル コントラクトによって起動すると、その戻るボタン戻る、アプリを起動した画面としないアプリの以前のコンテンツを確認します。When launched via Protocol Contract, make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content.

次のコードでは、プログラムで URI からアプリを起動しています。The following code programmatically launches the app via its URI:

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

URI からアプリを起動する方法について詳しくは、「URI に応じた既定のアプリの起動」をご覧ください。For more details about how to launch an app via a URI, see Launch the default app for a URI.

新しいページを開くアクティブ化イベントごとにアプリで新しい XAML フレームを作成することをお勧めします。It is recommended that apps create a new XAML Frame for each activation event that opens a new page. こうすると、新しい XAML フレームのナビゲーション バックスタックに、中断されたときに現在のウィンドウに表示されていた以前のコンテンツが含まれなくなります。This way, the navigation backstack for the new XAML Frame will not contain any previous content that the app might have on the current window when suspended. 起動コントラクトとファイル コントラクトで単一 XAML フレームを使うことにしたアプリは、新しいページに移動する前にフレームのナビゲーション ジャーナルにあるページをクリアする必要があります。Apps that decide to use a single XAML Frame for Launch and File Contracts should clear the pages on the Frame navigation journal before navigating to a new page.

プロトコルのアクティブ化によって起動されるときは、アプリの先頭ページに戻ることができる UI を含めることを検討してください。When launched via Protocol activation, apps should consider including UI that allows the user to go back to the top page of the app.

注釈Remarks

URI スキーム名は、悪意のあるものも含め、あらゆるアプリや Web サイトから使われる可能性があります。Any app or website can use your URI scheme name, including malicious ones. そのため、その URI で受け取るデータは、信頼できないソースからのデータである可能性があります。So any data that you get in the URI could come from an untrusted source. URI で受け取るパラメーターに基づいて永続的な操作を実行しないことをお勧めします。We recommend that you never perform a permanent action based on the parameters that you receive in the URI. たとえば、アプリを起動するとユーザーのアカウント ページが表示されるようにするために URI パラメーターを使うことはかまいませんが、ユーザーのアカウントを直接変更するためにプロトコル パラメーターを使うことは行わないことをお勧めします。For example, URI parameters could be used to launch the app to a user's account page, but we recommend that you never use them to directly modify the user's account.

注意

アプリの新しい URI スキーム名を作成する場合に、 RFC 4395のガイダンスに従ってください。If you are creating a new URI scheme name for your app, be sure to follow the guidance in RFC 4395. これにより確実に名前が URI スキームの標準に準拠するようになります。This ensures that your name meets the standards for URI schemes.

注意

プロトコル コントラクトによって起動すると、その戻るボタン戻る、アプリを起動した画面としないアプリの以前のコンテンツを確認します。When launched via Protocol Contract, make sure that Back button takes the user back to the screen that launched the app and not to the app's previous content.

新しい URI ターゲットを開くアクティブ化イベントごとに、アプリで新しい XAML フレームを作成することをお勧めします。We recommend that apps create a new XAML Frame for each activation event that opens a new Uri target. こうすると、新しい XAML フレームのナビゲーション バックスタックに、中断されたときに現在のウィンドウに表示されていた以前のコンテンツが含まれなくなります。This way, the navigation backstack for the new XAML Frame will not contain any previous content that the app might have on the current window when suspended.

アプリが、起動コントラクトとプロトコル コントラクトに単一 XAML フレームを使うようにした場合は、新しいページに移動する前にフレームのナビゲーション ジャーナルにあるページをクリアする必要があります。If you decide that you want your apps to use a single XAML Frame for Launch and Protocol Contracts, clear the pages on the Frame navigation journal before navigating to a new page. プロトコル コントラクトによって起動されるときは、アプリの先頭に戻ることができる UI をアプリに含めることを検討してください。When launched via Protocol Contract, consider including UI into your apps that allows the user to go back to the top of the app.

完全なサンプル アプリComplete sample app

概念Concepts

処理手順Tasks

ガイドラインGuidelines

リファレンスReference