Criar atividades de utilizador em aplicações do SDK de Aplicações Windows

As atividades do utilizador representam tarefas que um utilizador realiza na sua aplicação. Cria-se atividades para permitir que os utilizadores retomem de onde ficaram. As atividades aparecem no histórico local de atividades e podem ser apresentadas por funcionalidades do Windows que ajudam os utilizadores a regressar a tarefas anteriores.

Note

A sincronização na nuvem da Timeline foi descontinuada em julho de 2021. As atividades do utilizador criadas pela sua aplicação são armazenadas localmente e já não sincronizam entre dispositivos através do Microsoft Graph Timeline. O histórico local de atividade no dispositivo ainda funciona.

Pré-requisitos

  • A sua aplicação deve ser empacotada (MSIX) ou ter identidade de pacote.
  • Não é necessária qualquer declaração de capacidade especial — a API UserActivity está disponível para todas as aplicações empacotadas.

Criar uma atividade de utilizador

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 indica que o utilizador está atualmente envolvido nesta tarefa. Elimine-o quando o utilizador mudar para uma tarefa diferente.

Definir detalhes visuais detalhados

Use as propriedades em UserActivityVisualElements para descrever a atividade ao utilizador:

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) permitia renderizar um Cartão Adaptativo completo como visual de uma atividade, mas essa superfície fazia parte da Linha do Tempo do Windows, que a Microsoft retirou. Não use AdaptiveCardBuilder em código novo — use, em vez disso, as propriedades VisualElements mostradas acima.

Gerir a ativação a partir de uma atividade

Quando o utilizador seleciona uma atividade para retomar, a sua aplicação é ativada com um URI de protocolo. Trata disso na tua 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
    }
}

Fim da sessão

Quando o utilizador deixa de trabalhar na atividade, elimina a sessão:

UserActivitySession? _currentSession = null;

_currentSession?.Dispose();
_currentSession = null;

Melhores práticas

  • Use IDs de atividade significativos — O ID deve identificar de forma única a tarefa (por exemplo, um caminho de documento ou nome de projeto).
  • Atualize as atividades — Chame SaveAsync() quando o utilizador fizer progressos para manter a descrição atualizada.
  • Defina um URI de ativação — Forneça sempre um URI para que a atividade possa reiniciar a aplicação para o estado correto.
  • Crie uma sessão de cada vez — Elimine a sessão anterior antes de criar uma nova.

Para orientações detalhadas, consulte as melhores práticas de atividades dos utilizadores.

Conteúdo relacionado

  • Last updated on