Condividi tramite

Avviare un'app per ottenere risultati

  • Articolo

API importanti

Scopri come avviare un’app da un’altra app e scambiare dati tra le due. Questa operazione si chiama avvio di un'app per i risultati. L'esempio seguente illustra come usare LaunchUriForResultsAsync per avviare un'app per ottenere risultati.

Le nuove API di comunicazione da app ad app in Windows 10 consentono alle app di Windows (e alle app web di Windows) di avviare un'app e scambiare dati e file. In questo modo è possibile creare soluzioni mash-up da più app. Utilizzando queste nuove API, le attività complesse che avrebbero richiesto all'utente di utilizzare più app possono ora essere gestite senza problemi. Ad esempio, l'app potrebbe avviare un'app di social networking per scegliere un contatto o avviare un'app di checkout per completare un processo di pagamento.

L'app che verrà avviata per i risultati verrà definita app avviata. L'app che avvia l'app verrà definita app chiamante. Per questo esempio si scriveranno sia l'app chiamante che l'app avviata.

Passaggio 1: Registrare il protocollo da gestire nell'app che verrà avviata per i risultati

Nel file Package.appxmanifest dell'app avviata aggiungere un'estensione del protocollo alla sezione <Applicazione>. L'esempio seguente usa un protocollo fittizio denominato test-app2app.

L'attributo ReturnResults nell'estensione del protocollo accetta uno di questi valori:

In questo esempio di estensione del protocollo, l'app può essere avviata solo per i risultati. Questo semplifica la logica all'interno del metodo OnActivated, descritta di seguito, perché è necessario gestire solo il caso "avviato per i risultati" e non gli altri modi in cui l'app potrebbe essere attivata.

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

Passaggio 2: Eseguire l'override di Application.OnActivated nell'app che verrà avviata per i risultati

Se questo metodo non esiste già nell'app avviata, crearlo all'interno della classe App definita in App.xaml.cs.

In un'app che consente di selezionare gli amici in un social network, questa funzione potrebbe essere la posizione in cui si apre la pagina selezione persone. In questo esempio successivo viene visualizzata una pagina denominata LaunchedForResultsPage quando l'app viene attivata per i risultati. Assicurarsi che l'istruzione in uso sia inclusa nella parte superiore del 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();
}

using namespace winrt::Windows::ApplicationModel::Activation;
...
protected override void OnActivated(IActivatedEventArgs args)
{
    // Window management
    Frame rootFrame{ nullptr };
    auto content = Window::Current().Content();
    if (content)
    {
        rootFrame = content.try_as<Frame>();
    }
    
    if (rootFrame == null)
    {
        rootFrame = Frame();
        Window::Current().Content(rootFrame);
    }

    // Code specific to launch for results
    auto protocolForResultsEventArgs{ args.as<ProtocolForResultsActivatedEventArgs>() };
    // Open the page that we created to handle activation for results.
    rootFrame.Navigate(xaml_typename<LaunchedForResultsPage>(), protocolForResultsArgs);

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

Poiché l'estensione del protocollo nel file Package.appxmanifest specifica ReturnResults come sempre, il codice appena mostrato può essere trasmesso args direttamente a ProtocolForResultsActivatedEventArgs con fiducia che solo ProtocolForResultsActivatedEventArgs verrà inviato a OnActivated per questa app. Se la tua app può essere attivata in modi diversi dall'avvio per i risultati, puoi verificare se la proprietà IActivatedEventArgs.Kind restituisce ActivationKind.ProtocolForResults per indicare se l'app è stata avviata per ottenere risultati.

Passaggio 3: Aggiungere un campo ProtocolForResultsOperation all'app avviata per i risultati

private Windows.System.ProtocolForResultsOperation _operation = null;

Windows::System::ProtocolForResultsOperation _operation = nullptr;

Si userà il campo ProtocolForResultsOperation per segnalare quando l'app avviata è pronta per restituire il risultato all'app chiamante. In questo esempio, il campo viene aggiunto alla classe LaunchForResultsPage perché si completerà l'operazione launch-for-results da tale pagina e sarà necessario accedervi.

Passaggio 4: Eseguire l'override di OnNavigatedTo() nell'app avviata per i risultati

Eseguire l'override del metodo OnNavigatedTo nella pagina che verrà visualizzata all'avvio dell'app per ottenere risultati. Se questo metodo non esiste già, crearlo all'interno della classe per la pagina definita in <pagename>.xaml.cs. Assicurarsi che l'istruzione seguente in uso sia inclusa nella parte superiore del file:

using Windows.ApplicationModel.Activation

using namespace winrt::Windows::ApplicationModel::Activation;

L'oggetto NavigationEventArgs nel metodo OnNavigatedTo contiene i dati passati dall'app chiamante. I dati potrebbero non superare i 100 KB e vengono archiviati in un oggetto ValueSet.

In questo codice di esempio, l'app avviata prevede che i dati inviati dall'app chiamante si trovano in un ValueSet sotto una chiave chiamata TestData, perché questo è ciò a cui l'app di chiamata dell'esempio è codificata per inviare.

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;

using namespace winrt::Windows::ApplicationModel::Activation;
...
protected override void OnNavigatedTo(NavigationEventArgs e)
{
    auto protocolForResultsArgs = e.Parameter().try_as<ProtocolForResultsActivatedEventArgs>();
    // Set the ProtocolForResultsOperation field.
    _operation = protocolForResultsArgs.ProtocolForResultsOperation();

    if (protocolForResultsArgs.Data().HasKey("TestData"))
    {
        string dataFromCaller{ unbox_value<hstring>(protocolForResultsArgs.Data().Lookup("TestData")) };
    }
}
...
Windows::System::ProtocolForResultsOperation _operation = nullptr;

Passaggio 5: Scrivere codice per restituire i dati all'app chiamante

Nell'app avviata usare ProtocolForResultsOperation per restituire i dati all'app chiamante. In questo codice di esempio viene creato un oggetto ValueSet che contiene il valore da restituire all'app chiamante. Il campo ProtocolForResultsOperation viene quindi usato per inviare il valore all'app chiamante.

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

    ValueSet result;
    result.Insert("ReturnedData", "The returned result");
    _operation.ReportCompleted(result);

Passaggio 6: Scrivere codice per avviare l'app per ottenere i risultati e ottenere i dati restituiti

Avviare l'app dall'interno di un metodo asincrono nell'app chiamante, come illustrato in questo codice di esempio. Si notino le istruzioni in uso necessarie per la compilazione del codice:

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

In questo esempio viene passato un valore ValueSet contenente la chiave TestData all'app avviata. L'app avviata crea un oggetto ValueSet con una chiave denominata ReturnedData che contiene il risultato restituito al chiamante.

È necessario compilare e distribuire l'app che verrà avviata per i risultati prima di eseguire l'app chiamante. In caso contrario, LaunchUriResult.Status segnala LaunchUriStatus.AppUnavailable.

È necessario il nome della famiglia dell'app avviata quando si imposta TargetApplicationPackageFamilyName. Un modo per ottenere il nome della famiglia consiste nell'effettuare la chiamata seguente dall'interno dell'app avviata:

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

Osservazioni:

L'esempio in questa procedura fornisce un'introduzione "hello world" all'avvio di un'app per i risultati. Gli aspetti principali da notare sono che la nuova API LaunchUriForResultsAsync consente di avviare un'app in modo asincrono e comunicare tramite la classe ValueSet. Il passaggio di dati tramite ValueSet è limitato a 100 KB. Se è necessario passare grandi quantità di dati, è possibile condividere file usando la classe SharedStorageAccessManager per creare token di file che è possibile passare tra le app. Ad esempio, dato un ValoreSet denominato inputData, è possibile archiviare il token in un file che si vuole condividere con l'app avviata:

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

Passarlo quindi all'app avviata tramite LaunchUriForResultsAsync.