Iniciar una aplicación para obtener resultadosLaunch an app for results

API importantesImportant APIs

Aprende a iniciar una aplicación desde otra aplicación y a intercambiar datos entre las dos.Learn how to launch an app from another app and exchange data between the two. Esto se denomina iniciar una aplicación para obtener resultados.This is called launching an app for results. En el siguiente ejemplo se muestra cómo usar LaunchUriForResultsAsync para iniciar una aplicación para obtener resultados.The example here shows you how to use LaunchUriForResultsAsync to launch an app for results.

Las nuevas API de comunicación entre aplicaciones de Windows 10 hacen que las aplicaciones de Windows (y las aplicaciones web de Windows) puedan iniciar una aplicación e intercambiar archivos y datos.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. Esto te permite crear soluciones combinadas a partir de varias aplicaciones.This enables you to build mash-up solutions from multiple apps. Con estas nuevas API, las tareas complejas que hubieran requerido que el usuario usara varias aplicaciones ahora se pueden controlar sin problemas.Using these new APIs, complex tasks that would have required the user to use multiple apps can now be handled seamlessly. Por ejemplo, la aplicación podría iniciar una aplicación de redes sociales para elegir un contacto o iniciar una aplicación de confirmación de compra para completar un proceso de pago.For example, your app could launch a social networking app to choose a contact, or launch a checkout app to complete a payment process.

La aplicación que inicias para obtener resultados se denomina la aplicación iniciada.The app that you'll launch for results will be referred to as the launched app. La aplicación que inicia la aplicación se denomina aplicación que llama.The app that launches the app will be referred to as the calling app. Para este ejemplo escribirás tanto la aplicación que llama como la aplicación iniciada.For this example you will write both the calling app and the launched app.

Paso 1: registrar el protocolo que se controlará en la aplicación que se iniciará para obtener resultadosStep 1: Register the protocol to be handled in the app that you'll launch for results

En el archivo package. appxmanifest de la aplicación iniciada, agregue una extensión de protocolo a la sección de la ** < aplicación > ** .In the Package.appxmanifest file of the launched app, add a protocol extension to the <Application> section. En el siguiente ejemplo se usa un protocolo ficticio denominado test-app2app.The example here uses a fictional protocol named test-app2app.

El atributo ReturnResults de la extensión de protocolo acepta uno de estos valores:The ReturnResults attribute in the protocol extension accepts one of these values:

En este ejemplo de extensión de protocolo, la aplicación solo puede iniciarse para obtener resultados.In this protocol-extension example, the app can be launched only for results. Esto simplifica la lógica dentro del método OnActivated, que se explica a continuación, ya que solo hay que controlar el caso "iniciado para obtener resultados" y no el resto de maneras mediante las que se pudo activar la aplicación.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>

Paso 2: Reemplazar Application.OnActivated en la aplicación que iniciarás para obtener resultadosStep 2: Override Application.OnActivated in the app that you'll launch for results

Si este método ya no existe en la aplicación iniciada, créalo dentro de la clase App definida en App.xaml.cs.If this method does not already exist in the launched app, create it within the App class defined in App.xaml.cs.

En una aplicación que te permite elegir a tus amigos en una red social, esta función puede ser donde abres la página del selector de contactos.In an app that lets you pick your friends in a social network, this function could be where you open the people-picker page. En el siguiente ejemplo, se muestra una página llamada LaunchedForResultsPage cuando se activa la aplicación para obtener resultados.In this next example, a page named LaunchedForResultsPage is displayed when the app is activated for results. Asegúrate de que se incluya la instrucción using en la parte superior del archivo.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();
}

Como la extensión de protocolo del archivo Package.appxmanifest especifica ReturnResults como always, el código que se acaba de mostrar puede convertir args directamente en ProtocolForResultsActivatedEventArgs con la seguridad que solamente se enviará ProtocolForResultsActivatedEventArgs a OnActivated para esta aplicación.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. Si la aplicación se puede activar de otras maneras distintas de para la obtención de resultados, puedes comprobar si la propiedad IActivatedEventArgs.Kind devuelve ActivationKind.ProtocolForResults para indicar si la aplicación se inició para obtener resultados.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.

Paso 3: agregar un campo ProtocolForResultsOperation a la aplicación que se inicia para obtener resultadosStep 3: Add a ProtocolForResultsOperation field to the app you launch for results

private Windows.System.ProtocolForResultsOperation _operation = null;

El campo ProtocolForResultsOperation se usará para indicar el momento en que la aplicación iniciada esté lista para devolver el resultado a la aplicación que llama.You'll use the ProtocolForResultsOperation field to signal when the launched app is ready to return the result to the calling app. En este ejemplo, el campo se agrega a la clase LaunchedForResultsPage porque se completará la operación de inicio para obtener resultados desde esa página y se necesitará tener acceso a él.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.

Paso 4: reemplazar OnNavigatedTo() en la aplicación que se inicia para obtener resultadosStep 4: Override OnNavigatedTo() in the app you launch for results

Reemplaza el método OnNavigatedTo en la página que se mostrará cuando se inicie la aplicación para obtener los resultados.Override the OnNavigatedTo method on the page that you'll display when your app is launched for results. Si este método aún no existe, créalo dentro de la clase de la página definida en <nombrepágina>.xaml.cs.If this method does not already exist, create it within the class for the page defined in <pagename>.xaml.cs. Asegúrate de que se incluye la siguiente instrucción using en la parte superior del archivo:Ensure that the following using statement is included at the top of the file:

using Windows.ApplicationModel.Activation

El objeto NavigationEventArgs del método OnNavigatedTo contiene los datos pasados desde la aplicación que llama.The NavigationEventArgs object in the OnNavigatedTo method contains the data passed from the calling app. Los datos no puede superar los 100 KB y se almacenan en un objeto ValueSet.The data may not exceed 100KB and is stored in a ValueSet object.

En el código de ejemplo siguiente, la aplicación iniciada espera que los datos enviados desde la aplicación que llama estén en un elemento ValueSet, en una clave denominada TestData, ya que así es como se ha codificado que realice el envío la aplicación que llama del ejemplo.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;

Paso 5: escribir código para devolver datos a la aplicación que llamaStep 5: Write code to return data to the calling app

En la aplicación iniciada, usa ProtocolForResultsOperation para devolver los datos a la aplicación que llama.In the launched app, use ProtocolForResultsOperation to return data to the calling app. En el código de ejemplo siguiente, se crea un objeto ValueSet que contiene el valor que se devolverá a la aplicación que llama.In this example code, a ValueSet object is created that contains the value to return to the calling app. Después, se usa el campo ProtocolForResultsOperation para enviar el valor a la aplicación que llama.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);

Paso 6: escribir código para iniciar la aplicación para obtener resultados y obtener los datos devueltosStep 6: Write code to launch the app for results and get the returned data

Inicia la aplicación desde dentro de un método asincrónico en la aplicación que llama tal y como se muestra en el ejemplo de código siguiente.Launch the app from within an async method in your calling app as shown in this example code. Observa las instrucciones using, que son necesarias compilar el código: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;
}

En este ejemplo, un elemento ValueSet que contiene la clave TestData se pasa a la aplicación iniciada.In this example, a ValueSet containing the key TestData is passed to the launched app. La aplicación iniciada crea un elemento ValueSet con una clave denominada ReturnedData que contiene el resultado que se devuelve al llamador.The launched app creates a ValueSet with a key named ReturnedData that contains the result returned to the caller.

Debes compilar e implementar la aplicación que se iniciará para obtener resultados antes de ejecutar la aplicación que llama.You must build and deploy the app that you'll launch for results before running your calling app. De lo contrario, LaunchUriResult.Status notificará LaunchUriStatus.AppUnavailable.Otherwise, LaunchUriResult.Status will report LaunchUriStatus.AppUnavailable.

Necesitarás el nombre de familia de la aplicación iniciada cuando establezcas la propiedad TargetApplicationPackageFamilyName.You'll need the family name of the launched app when you set the TargetApplicationPackageFamilyName. Una forma de obtener el nombre de familia es realizar la siguiente llamada desde la aplicación iniciada: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;

ObservacionesRemarks

En el ejemplo de este procedimiento se ofrece una introducción de tipo "hola a todos" a fin de iniciar una aplicación para obtener resultados.The example in this how-to provides a "hello world" introduction to launching an app for results. Los conceptos clave que se deben tener en cuenta son que la nueva API LaunchUriForResultsAsync permite iniciar una aplicación de manera asincrónica y comunicarse a través de la clase ValueSet.The key things to note are that the new LaunchUriForResultsAsync API lets you asynchronously launch an app and communicate via the ValueSet class. La transmisión de datos a través de un elemento ValueSet está limitada a 100 KB.Passing data via a ValueSet is limited to 100KB. Si necesitas transmitir mayores volúmenes de datos, puedes compartir archivos mediante la clase SharedStorageAccessManager para crear tokens de archivo que se puedan pasar entre aplicaciones.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. Por ejemplo, si existe un elemento ValueSet denominado inputData, podrías almacenar el token en un archivo que quieras compartir con la aplicación iniciada: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);

Después, pásalo a la aplicación iniciada mediante LaunchUriForResultsAsync.Then pass it to the launched app via LaunchUriForResultsAsync.