Creare attività utente nelle app di SDK per app di Windows

Le attività utente rappresentano le attività eseguite da un utente nell'app. Le attività vengono create per consentire agli utenti di riprendere la posizione in cui sono stati interrotti. Le attività vengono visualizzate nella cronologia delle attività locali e possono essere visualizzate da Windows funzionalità che consentono agli utenti di tornare alle attività precedenti.

Note

La sincronizzazione cloud di Timeline è stata deprecata nel luglio 2021. Le attività utente create dall'app vengono archiviate in locale e non vengono più sincronizzate tra i dispositivi tramite Microsoft Graph Sequenza temporale. La cronologia delle attività locali nel dispositivo funziona ancora.

Prerequisiti

  • L'app deve essere inserita in un pacchetto (MSIX) o avere un'identità del pacchetto.
  • Non è necessaria alcuna dichiarazione di funzionalità speciale: l'API UserActivity è disponibile per tutte le app in pacchetto.

Creare un'attività utente

Usare le classi UserActivityChannel e UserActivity :

using Windows.ApplicationModel.UserActivities;

private UserActivitySession? _currentSession;

private async Task CreateActivityAsync()
{
    var channel = UserActivityChannel.GetDefault();
    var activity = await channel.GetOrCreateUserActivityAsync("document-123");

    activity.ActivationUri = new Uri("myapp://open?doc=123");
    activity.VisualElements.DisplayText = "Quarterly Report";
    activity.VisualElements.Description = "Working on Q4 financial summary";

    await activity.SaveAsync();
    _currentSession = activity.CreateSession();
}

La sessione di attività segnala che l'utente è attualmente impegnato con questa attività. Eliminarlo quando l'utente passa a un'attività diversa.

Impostare dettagli visivi avanzati

Usare le proprietà in UserActivityVisualElements per descrivere l'attività all'utente:

UserActivity activity = new UserActivity("quarterly-report");

activity.VisualElements.DisplayText = "Quarterly Report";
activity.VisualElements.Description = "Last edited: Section 3 - Revenue Analysis";
activity.VisualElements.Attribution = new UserActivityAttribution(
    new Uri("ms-appx:///Assets/AppIcon.png"));

Note

AdaptiveCardBuilder (Windows.UI.Shell) consentono di eseguire il rendering di una scheda adattiva completa come elemento visivo di un'attività, ma tale interfaccia faceva parte della Sequenza temporale di Windows, che Microsoft ha ritirato. Non usare AdaptiveCardBuilder nel nuovo codice: usare invece le VisualElements proprietà mostrate in precedenza.

Gestire l'attivazione da un'attività

Quando l'utente seleziona un'attività da riprendere, l'app viene attivata con un URI del protocollo. Gestiscilo nella logica di attivazione:

var activatedArgs = AppInstance.GetCurrent().GetActivatedEventArgs();

if (activatedArgs.Kind == ExtendedActivationKind.Protocol)
{
    var protocolArgs = activatedArgs.Data as Windows.ApplicationModel.Activation.IProtocolActivatedEventArgs;
    if (protocolArgs?.Uri.Scheme == "myapp")
    {
        // Parse the query string manually; System.Web.HttpUtility isn't
        // available to apps that target .NET (as opposed to .NET Framework).
        string? docId = protocolArgs.Uri.Query
            .TrimStart('?')
            .Split('&', StringSplitOptions.RemoveEmptyEntries)
            .Select(pair => pair.Split('=', 2))
            .FirstOrDefault(pair => pair[0] == "doc")
            ?.ElementAtOrDefault(1);
        // Navigate to the document
    }
}

Terminare la sessione

Quando l'utente smette di lavorare sull'attività, eliminare la sessione:

UserActivitySession? _currentSession = null;

_currentSession?.Dispose();
_currentSession = null;

Procedure consigliate

  • Usare ID attività significativi : l'ID deve identificare in modo univoco l'attività, ad esempio un percorso di documento o un nome di progetto.
  • Attività di aggiornamento : chiamare SaveAsync() quando l'utente procede per mantenere aggiornata la descrizione.
  • Impostare un URI di attivazione : fornire sempre un URI in modo che l'attività possa riavviare l'app allo stato corretto.
  • Crea una sessione alla volta : elimina la sessione precedente prima di crearne una nuova.

Per indicazioni dettagliate, vedere Procedure consigliate per le attività utente.

Contenuti correlati

  • Last updated on