Criar atividades do usuário em aplicativos SDK do Aplicativo Windows

As atividades do usuário representam tarefas que um usuário executa em seu aplicativo. Você cria atividades para permitir que os usuários retomem de onde pararam. As atividades aparecem no histórico de atividades local e podem ser exibidas por recursos do Windows que ajudam os usuários a voltar a tarefas anteriores.

Note

A sincronização em nuvem da Linha do Tempo foi descontinuada em julho de 2021. As atividades do usuário criadas pelo aplicativo são armazenadas localmente e não são mais sincronizadas entre dispositivos por meio de Microsoft Graph Linha do Tempo. O histórico de atividades local no dispositivo ainda funciona.

Pré-requisitos

  • Seu aplicativo deve ser empacotado (MSIX) ou ter identidade de pacote.
  • Nenhuma declaração de funcionalidade especial é necessária – a API UserActivity está disponível para todos os aplicativos empacotados.

Criar uma atividade do usuário

Use as classes 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();
}

A sessão de atividade sinaliza que o usuário está envolvido com essa tarefa no momento. Descarte-o quando o usuário alternar para uma tarefa diferente.

Definir detalhes visuais ricos

Use as propriedades em UserActivityVisualElements para descrever a atividade para o usuário:

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) permitem a você renderizar um cartão adaptável completo como o elemento visual de uma atividade, mas essa superfície fazia parte da Linha do Tempo do Windows, que a Microsoft descontinuou. Não use AdaptiveCardBuilder em códigos novos; use as propriedades VisualElements mostradas acima.

Manipular ativação com base em uma atividade

Quando o usuário seleciona uma atividade a ser retomada, seu aplicativo é ativado com um URI de protocolo. Trate isso na sua lógica de ativação:

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

Encerrar a sessão

Quando o usuário parar de trabalhar na atividade, descarte a sessão:

UserActivitySession? _currentSession = null;

_currentSession?.Dispose();
_currentSession = null;

Práticas recomendadas

  • Usar IDs de atividade significativas — a ID deve identificar exclusivamente a tarefa (por exemplo, um caminho de documento ou nome do projeto).
  • Atividades de atualização – chame SaveAsync() quando o usuário fizer progressos para manter a descrição atual.
  • Definir um URI de ativação – sempre forneça um URI para que a atividade possa relançar o aplicativo para o estado correto.
  • Criar uma sessão de cada vez – descarte a sessão anterior antes de criar uma.

Para obter diretrizes detalhadas, consulte as práticas recomendadas das atividades do usuário.

Conteúdo relacionado

  • Last updated on