結果を取得するためのアプリの起動Launch an app for results

重要な APIImportant APIs

別のアプリからアプリを起動し、2 つのアプリの間でデータを交換する方法について説明します。Learn how to launch an app from another app and exchange data between the two. これは 、結果のアプリの起動と呼ばれます。This is called launching an app for results. この例では、LaunchUriForResultsAsync を使って、結果を取得するためのアプリの起動方法を示しています。The example here shows you how to use LaunchUriForResultsAsync to launch an app for results.

Windows 10 での新しいアプリ間通信 API により、各 Windows アプリ (および Windows Web アプリ) 間でのアプリの起動と、データおよびファイルの交換が可能になります。New app-to-app communication APIs in Windows 10 make it possible for Windows apps (and Windows Web apps) to launch an app and exchange data and files. このため、複数のアプリを基にマッシュアップ ソリューションを構築できます。This enables you to build mash-up solutions from multiple apps. これらの新しい API を使うと、複数のアプリを使う必要のあった複雑な作業をシームレスに処理できるようになります。Using these new APIs, complex tasks that would have required the user to use multiple apps can now be handled seamlessly. たとえば、アプリでソーシャル ネットワーキング アプリを起動して連絡先を選んだり、チェックアウト アプリを起動して支払処理を実行したりすることができます。For example, your app could launch a social networking app to choose a contact, or launch a checkout app to complete a payment process.

結果を得るために起動するアプリは、起動されたアプリと呼ばれます。The app that you'll launch for results will be referred to as the launched app. アプリを起動するアプリは、呼び出し元アプリと呼ばれます。The app that launches the app will be referred to as the calling app. この例では、呼び出し元アプリと、起動されたアプリの両方を記述します。For this example you will write both the calling app and the launched app.

手順 1: 結果を取得するために起動するアプリで処理されるプロトコルを登録するStep 1: Register the protocol to be handled in the app that you'll launch for results

起動したアプリの package.appxmanifest ファイルで、 ** < アプリケーション > **セクションにプロトコル拡張機能を追加します。In the Package.appxmanifest file of the launched app, add a protocol extension to the <Application> section. この例では、test-app2app という名前の架空プロトコルを使います。The example here uses a fictional protocol named test-app2app.

プロトコル拡張機能の ReturnResults 属性に指定できる値は、次の 3 つのうちいずれかです。The ReturnResults attribute in the protocol extension accepts one of these values:

  • optional—結果を取得するためにアプリを起動する場合は、LaunchUriForResultsAsync メソッドを使います。結果を取得しない場合は、LaunchUriAsync を使います。optional—The app can be launched for results by using the LaunchUriForResultsAsync method, or not for results by using LaunchUriAsync. optional を使うとき、起動アプリでは、結果を取得するためにアプリが起動されたかどうかを判別する必要があります。When you use optional, the launched app must determine whether it was launched for results. これを行うには、OnActivated イベント引数を調べます。It can do that by checking the OnActivated event argument. 引数の IActivatedEventArgs.Kind プロパティが ActivationKind.ProtocolForResults を返した場合、またはイベント引数の型が ProtocolActivatedEventArgs である場合は、アプリが LaunchUriForResultsAsync を介して起動されます。If the argument's IActivatedEventArgs.Kind property returns ActivationKind.ProtocolForResults, or if the type of the event argument is ProtocolActivatedEventArgs, the app was launched via LaunchUriForResultsAsync.
  • always—アプリは、結果を取得するためにのみ起動することができます。つまり、LaunchUriForResultsAsync に対してのみ応答できます。always—The app can be launched only for results; that is, it can respond only to LaunchUriForResultsAsync.
  • none—アプリは、結果を取得するために起動することはできません。LaunchUriAsync に対してのみ応答できます。none—The app cannot be launched for results; it can respond only to LaunchUriAsync.

次のプロトコル拡張機能の例では、アプリは結果を取得するためにのみ起動することができます。In this protocol-extension example, the app can be launched only for results. 以下で説明するように、この例では、OnActivated メソッド内部のロジックが簡素化されます。これは、"結果を取得するために起動する" ケースのみを処理し、アプリをアクティブ化する他の方法を処理する必要がないためです。This simplifies the logic inside the OnActivated method, discussed below, because we have to handle only the "launched for results" case and not the other ways that the app could be activated.

<Applications>
   <Application ...>

     <Extensions>
       <uap:Extension Category="windows.protocol">
         <uap:Protocol Name="test-app2app" ReturnResults="always">
           <uap:DisplayName>Test app-2-app</uap:DisplayName>
         </uap:Protocol>
       </uap:Extension>
     </Extensions>

   </Application>
</Applications>

手順 2: 結果を取得するために起動するアプリで Application.OnActivated をオーバーライドするStep 2: Override Application.OnActivated in the app that you'll launch for results

このメソッドが起動アプリにまだ存在しない場合は、App.xaml.cs で定義されている App クラス内に作成します。If this method does not already exist in the launched app, create it within the App class defined in App.xaml.cs.

ソーシャル ネットワークで友だちを選ぶことができるアプリでは、この関数によって友だちを選ぶためのページを開くことができます。In an app that lets you pick your friends in a social network, this function could be where you open the people-picker page. 次の例では、LaunchedForResultsPage という名前のページが、結果を取得するためにアプリがアクティブ化されたときに表示されます。In this next example, a page named LaunchedForResultsPage is displayed when the app is activated for results. ファイルの先頭に、次の using ステートメントが含まれていることを確認します。Ensure that the using statement is included at the top of the file.

using Windows.ApplicationModel.Activation;
...
protected override void OnActivated(IActivatedEventArgs args)
{
    // Window management
    Frame rootFrame = Window.Current.Content as Frame;
    if (rootFrame == null)
    {
        rootFrame = new Frame();
        Window.Current.Content = rootFrame;
    }

    // Code specific to launch for results
    var protocolForResultsArgs = (ProtocolForResultsActivatedEventArgs)args;
    // Open the page that we created to handle activation for results.
    rootFrame.Navigate(typeof(LaunchedForResultsPage), protocolForResultsArgs);

    // Ensure the current window is active.
    Window.Current.Activate();
}

Package.appxmanifest ファイル内のプロトコル拡張機能では ReturnResultsalways と指定されているため、上記のコードでは argsProtocolForResultsActivatedEventArgs に直接キャストすることができます。このとき、ProtocolForResultsActivatedEventArgs のみが、このアプリの OnActivated に送信されます。Because the protocol extension in the Package.appxmanifest file specifies ReturnResults as always, the code just shown can cast args directly to ProtocolForResultsActivatedEventArgs with confidence that only ProtocolForResultsActivatedEventArgs will be sent to OnActivated for this app. 結果を取得するための起動以外の方法でアプリがアクティブ化される可能性がある場合は、結果を取得するためにアプリが起動されたかどうかを判別するために IActivatedEventArgs.Kind プロパティが ActivationKind.ProtocolForResults を返すかどうかを確認してください。If your app can be activated in ways other than launching for results, you can check whether IActivatedEventArgs.Kind property returns ActivationKind.ProtocolForResults to tell whether the app was launched for results.

手順 3: 結果を取得するために起動するアプリに ProtocolForResultsOperation フィールドを追加するStep 3: Add a ProtocolForResultsOperation field to the app you launch for results

private Windows.System.ProtocolForResultsOperation _operation = null;

ProtocolForResultsOperation フィールドを使うと、起動されたアプリが呼び出し元のアプリに結果を返すことができるようになった場合に、そのタイミングを通知することができます。You'll use the ProtocolForResultsOperation field to signal when the launched app is ready to return the result to the calling app. この例では、このフィールドは LaunchedForResultsPage クラスに追加されます。これは、結果を取得するための起動処理をそのページから実行し、そのページにアクセスする必要があるためです。In this example, the field is added to the LaunchedForResultsPage class because you'll complete the launch-for-results operation from that page and will need access to it.

手順 4: 結果を取得するために起動するアプリで OnNavigatedTo() をオーバーライドするStep 4: Override OnNavigatedTo() in the app you launch for results

結果を取得するためにアプリを起動するときに表示するページで、OnNavigatedTo メソッドをオーバーライドします。Override the OnNavigatedTo method on the page that you'll display when your app is launched for results. このメソッドがまだ存在しない場合は、<ページ名>.xaml.cs で定義されているページのクラス内に作成します。If this method does not already exist, create it within the class for the page defined in <pagename>.xaml.cs. ファイルの先頭に、次の using ステートメントが含まれていることを確認します。Ensure that the following using statement is included at the top of the file:

using Windows.ApplicationModel.Activation

OnNavigatedTo メソッド内の NavigationEventArgs オブジェクトには、呼び出し元アプリから渡されたデータが含まれます。The NavigationEventArgs object in the OnNavigatedTo method contains the data passed from the calling app. データは最大で 100 KB になります。また、データは ValueSet オブジェクトに格納されます。The data may not exceed 100KB and is stored in a ValueSet object.

次のコード例では、起動されたアプリは、呼び出し元のアプリから送信されたデータが TestData というキーで ValueSet に格納されていることを想定しています。これは、サンプルの呼び出し元アプリで、データを送信するためにそのようにコード化されているためです。In this example code, the launched app expects the data sent from the calling app to be in a ValueSet under a key named TestData, because that's what the example's calling app is coded to send.

using Windows.ApplicationModel.Activation;
...
protected override void OnNavigatedTo(NavigationEventArgs e)
{
    var protocolForResultsArgs = e.Parameter as ProtocolForResultsActivatedEventArgs;
    // Set the ProtocolForResultsOperation field.
    _operation = protocolForResultsArgs.ProtocolForResultsOperation;

    if (protocolForResultsArgs.Data.ContainsKey("TestData"))
    {
        string dataFromCaller = protocolForResultsArgs.Data["TestData"] as string;
    }
}
...
private Windows.System.ProtocolForResultsOperation _operation = null;

手順 5: 呼び出し元のアプリにデータを返すコードを記述するStep 5: Write code to return data to the calling app

起動アプリで、ProtocolForResultsOperation を使って呼び出し元のアプリにデータを返します。In the launched app, use ProtocolForResultsOperation to return data to the calling app. 次のコード例では、呼び出し元のアプリに返す値を格納する ValueSet オブジェクトが作成されます。In this example code, a ValueSet object is created that contains the value to return to the calling app. その後で、ProtocolForResultsOperation フィールドを使って、呼び出し元のアプリに値を送信します。The ProtocolForResultsOperation field is then used to send the value to the calling app.

    ValueSet result = new ValueSet();
    result["ReturnedData"] = "The returned result";
    _operation.ReportCompleted(result);

手順 6: 結果を取得するためにアプリを起動し、返されたデータを取得するコードを記述するStep 6: Write code to launch the app for results and get the returned data

次のコード例に示すように、呼び出し元のアプリの非同期メソッド内で、アプリを起動します。Launch the app from within an async method in your calling app as shown in this example code. using ステートメントは、コードをコンパイルするために必要となります。Note the using statements, which are necessary for the code to compile:

using System.Threading.Tasks;
using Windows.System;
...

async Task<string> LaunchAppForResults()
{
    var testAppUri = new Uri("test-app2app:"); // The protocol handled by the launched app
    var options = new LauncherOptions();
    options.TargetApplicationPackageFamilyName = "67d987e1-e842-4229-9f7c-98cf13b5da45_yd7nk54bq29ra";

    var inputData = new ValueSet();
    inputData["TestData"] = "Test data";

    string theResult = "";
    LaunchUriResult result = await Windows.System.Launcher.LaunchUriForResultsAsync(testAppUri, options, inputData);
    if (result.Status == LaunchUriStatus.Success &&
        result.Result != null &&
        result.Result.ContainsKey("ReturnedData"))
    {
        ValueSet theValues = result.Result;
        theResult = theValues["ReturnedData"] as string;
    }
    return theResult;
}

この例では、キー TestData を含んでいる ValueSet が、起動アプリに渡されます。In this example, a ValueSet containing the key TestData is passed to the launched app. 起動アプリは、ReturnedData という名前のキーを持つ ValueSet を作成します。これには、呼び出し元に返される結果が含まれています。The launched app creates a ValueSet with a key named ReturnedData that contains the result returned to the caller.

結果を取得するために起動するアプリは、呼び出し元アプリを実行する前にビルドし、展開する必要があります。You must build and deploy the app that you'll launch for results before running your calling app. このように操作しないと、LaunchUriResult.StatusLaunchUriStatus.AppUnavailable を報告します。Otherwise, LaunchUriResult.Status will report LaunchUriStatus.AppUnavailable.

TargetApplicationPackageFamilyName を設定するときは、起動アプリのファミリ名が必要です。You'll need the family name of the launched app when you set the TargetApplicationPackageFamilyName. ファミリ名を取得する方法の 1 つは、起動アプリ内から、次の呼び出しを行うことです。One way to get the family name is to make the following call from within the launched app:

string familyName = Windows.ApplicationModel.Package.Current.Id.FamilyName;

注釈Remarks

この方法の例については、結果を取得するためのアプリの起動の概要を説明した "hello world" アプリをご覧ください。The example in this how-to provides a "hello world" introduction to launching an app for results. 重要な注意点は、新しい LaunchUriForResultsAsync API を使うと、アプリを非同期的に起動し、ValueSet クラスを使って通信できるようになることです。The key things to note are that the new LaunchUriForResultsAsync API lets you asynchronously launch an app and communicate via the ValueSet class. ValueSet を使って渡すデータは、100 KB に制限されます。Passing data via a ValueSet is limited to 100KB. より多くのデータを渡す必要がある場合は、アプリ間で渡すことができるファイル トークンを作成するための、SharedStorageAccessManager クラスを使ってファイルを共有することができます。If you need to pass larger amounts of data, you can share files by using the SharedStorageAccessManager class to create file tokens that you can pass between apps. たとえば、inputData という名前の ValueSet を指定し、起動アプリと共有するファイルのトークンを格納できます。For example, given a ValueSet named inputData, you could store the token to a file that you want to share with the launched app:

inputData["ImageFileToken"] = SharedStorageAccessManager.AddFile(myFile);

その後で、LaunchUriForResultsAsync を使って、トークンを起動アプリに渡します。Then pass it to the launched app via LaunchUriForResultsAsync.