Ricevere dati

  • Articolo

Questo articolo illustra come ricevere contenuto nell'app UWP (Universal Windows Platform) condiviso da un'altra app usando il contratto di condivisione. Questo contratto Condivisione permette di presentare la tua app come un'opzione quando l'utente richiama la condivisione.

Dichiarare l'app come destinazione di condivisione

Il sistema visualizza un elenco di possibili app di destinazione quando un utente richiama Condivisione. Per essere visualizzata nell'elenco, l'app deve dichiarare che supporta il contratto di condivisione. In questo modo il sistema sa che l'app è disponibile per ricevere contenuto.

  1. Aprire il file manifesto. Dovrebbe essere chiamato qualcosa come package.appxmanifest.
  2. Aprire la scheda Dichiarazioni.
  3. Scegliere Condividi destinazione dall'elenco Dichiarazioni disponibili e quindi selezionare Aggiungi.

Scegliere tipi e formati di file

Successivamente, decidere quali tipi di file e formati di dati sono supportati. Le API di condivisione supportano diversi formati standard, ad esempio Testo, HTML e Bitmap. È anche possibile specificare tipi di file e formati di dati personalizzati. In tal caso, tenere presente che le app di origine devono sapere quali tipi e formati sono; in caso contrario, tali app non possono usare i formati per condividere i dati.

Registrarsi solo per i formati che l'app può gestire. Vengono visualizzate solo le app di destinazione che supportano i dati condivisi quando l'utente richiama Condivisione.

Per impostare i tipi di file:

  1. Aprire il file manifesto. Dovrebbe essere chiamato qualcosa come package.appxmanifest.
  2. Nella sezione Tipi di file supportati della pagina Dichiarazioni selezionare Aggiungi nuovo.
  3. Digitare l'estensione del nome di file che si desidera supportare, ad esempio ".docx". È necessario includere il periodo. Per supportare tutti i tipi di file, selezionare la casella di controllo SupportsAnyFileType.

Per impostare i formati di dati:

  1. Aprire il file manifesto.
  2. Aprire la sezione Formati dati della pagina Dichiarazioni e quindi selezionare Aggiungi nuovo.
  3. Digitare il nome del formato di dati supportato, ad esempio "Text".

Gestire l'attivazione della condivisione

Quando un utente seleziona l'app (in genere selezionandola da un elenco di app di destinazione disponibili nell'interfaccia utente di condivisione), viene generato un evento OnShareTargetActivated. L'app deve gestire questo evento per elaborare i dati che l'utente vuole condividere.

protected override async void OnShareTargetActivated(ShareTargetActivatedEventArgs args)
{
    // Code to handle activation goes here. 
}

I dati che l'utente desidera condividere sono contenuti in un oggetto ShareOperation. È possibile utilizzare questo oggetto per controllare il formato dei dati contenuti.

ShareOperation shareOperation = args.ShareOperation;
if (shareOperation.Data.Contains(StandardDataFormats.Text))
{
    string text = await shareOperation.Data.GetTextAsync();

    // To output the text from this example, you need a TextBlock control
    // with a name of "sharedContent".
    sharedContent.Text = "Text: " + text;
}

Stato condivisione report

In alcuni casi, l'elaborazione dei dati da condividere da parte dell'app può richiedere tempo. Ad esempio, gli utenti condividono raccolte di file o immagini. Questi elementi sono più grandi di una semplice stringa di testo, quindi richiedono più tempo per l'elaborazione.

shareOperation.ReportStarted();

Dopo aver chiamato ReportStarted, non aspettatevi altre interazioni utente con l'app. Di conseguenza, non dovresti chiamarla a meno che l'app non sia in un punto in cui può essere ignorata dall'utente.

Con una condivisione estesa, è possibile che l'utente possa ignorare l'app di origine prima che l'app abbia tutti i dati dell'oggetto DataPackage. Di conseguenza, ti consigliamo di informare il sistema quando l'app ha acquisito i dati necessari. In questo modo, il sistema può sospendere o terminare l'app di origine in base alle esigenze.

shareOperation.ReportSubmittedBackgroundTask();

In caso di errore, chiamare ReportError per inviare un messaggio di errore al sistema. L'utente visualizzerà il messaggio quando controlla lo stato della condivisione. A questo punto, l'app viene arrestata e la condivisione viene terminata. L'utente dovrà ricominciare a condividere il contenuto nell'app. A seconda dello scenario, è possibile decidere che un determinato errore non è sufficientemente grave da terminare l'operazione di condivisione. In tal caso, è possibile scegliere di non chiamare ReportError e continuare con la condivisione.

shareOperation.ReportError("Could not reach the server! Try again later.");

Infine, quando l'app ha elaborato correttamente il contenuto condiviso, devi chiamare ReportCompleted per informare il sistema.

shareOperation.ReportCompleted();

Quando si usano questi metodi, in genere vengono chiamati nell'ordine appena descritto e non vengono chiamati più di una volta. Tuttavia, in alcuni casi un'app di destinazione può chiamare ReportDataRetrieved prima di ReportStarted. Ad esempio, l'app potrebbe recuperare i dati come parte di un'attività nel gestore di attivazione, ma non chiamare ReportStarted finché l'utente non seleziona un pulsante Condividi .

Quando un utente seleziona l'app per ricevere contenuto, è consigliabile creare un collegamento rapido. Un collegamento rapido è simile a un collegamento che semplifica la condivisione delle informazioni con l'app da parte degli utenti. Ad esempio, è possibile creare un collegamento rapido che apre un nuovo messaggio di posta elettronica preconfigurato con l'indirizzo di posta elettronica di un amico.

Un collegamento rapido deve avere un titolo, un'icona e un ID. Il titolo (ad esempio "Email Mom") e l'icona vengono visualizzati quando l'utente tocca l'accesso Condividi. L'ID è ciò che l'app usa per accedere a qualsiasi informazione personalizzata, ad esempio un indirizzo di posta elettronica o credenziali di accesso. Quando l'app crea un QuickLink, l'app restituisce il QuickLink al sistema chiamando ReportCompleted.

Un quicklink non archivia effettivamente i dati. Contiene invece un identificatore che, quando selezionato, viene inviato all'app. L'app è responsabile dell'archiviazione dell'ID del collegamento rapido e dei dati utente corrispondenti. Quando l'utente tocca quicklink, è possibile ottenere il relativo ID tramite la proprietà QuickLink, you can get its Id through the QuickLinkId.

async void ReportCompleted(ShareOperation shareOperation, string quickLinkId, string quickLinkTitle)
{
    QuickLink quickLinkInfo = new QuickLink
    {
        Id = quickLinkId,
        Title = quickLinkTitle,

        // For quicklinks, the supported FileTypes and DataFormats are set 
        // independently from the manifest
        SupportedFileTypes = { "*" },
        SupportedDataFormats = { StandardDataFormats.Text, StandardDataFormats.Uri, 
                StandardDataFormats.Bitmap, StandardDataFormats.StorageItems }
    };

    StorageFile iconFile = await Windows.ApplicationModel.Package.Current.InstalledLocation.CreateFileAsync(
            "assets\\user.png", CreationCollisionOption.OpenIfExists);
    quickLinkInfo.Thumbnail = RandomAccessStreamReference.CreateFromFile(iconFile);
    shareOperation.ReportCompleted(quickLinkInfo);
}

Vedi anche