Idioma: HTML | XAML

Guia de início rápido: criando e registrando uma tarefa em segundo plano de notificação bruta (XAML)

Applies to Windows and Windows Phone

Observação  Não está usando C#/VB/C++? Veja Guia de início rápido: criando e registrando uma tarefa em segundo plano de notificação bruta (HTML).

Você pode criar e registrar uma função de tarefa em segundo plano para o seu aplicativo da Windows Store. Esse código é executado em resposta ao recebimento de uma notificação bruta, que confere funcionalidade ao seu aplicativo quando ele não está em primeiro plano.

Para concluir esse procedimento, você deve editar três arquivos separados: o código do aplicativo, o manifesto do aplicativo e um novo arquivo que contenha o código da tarefa em segundo plano.

Pré-requisitos

Para compreender este tópico ou para usar o código que ele oferece, você precisará de:

Instruções

1. Criar a classe da tarefa em segundo plano

Para executar códigos em segundo plano, você deve criar uma classe que implemente a interface IBackgroundTask, como mostrado nos exemplos a seguir. Essa classe é executada quando uma notificação bruta é entregue.

Para começar, crie um novo projeto na solução do aplicativo. Esse projeto conterá o código da tarefa em segundo plano. Importe o namespace Windows.ApplicationModel.Background para o projeto. Adicione um arquivo de código ao projeto. Neste caso, adicionaremos um arquivo em C# intitulado ExampleBackgroundTask.cs.

No arquivo ExampleBackgroundTask.cs, crie uma nova classe que implemente a interface IBackgroundTask. O método Run da interface deve estar presente em todas as tarefas em segundo plano como um ponto de entrada que será chamado quando o evento específico for acionado.

O exemplo a seguir mostra um ponto inicial bastante básico para a classe de tarefa em segundo plano. O corpo do código, específico ao conteúdo da notificação bruta definida pelo aplicativo, substituirá o comentário "// ...".



using Windows.ApplicationModel.Background;
using Windows.Networking.PushNotifications;

namespace Tasks
{
    public sealed class ExampleBackgroundTask : IBackgroundTask
    {
        public void Run(IBackgroundTaskInstance taskInstance)
        {
            RawNotification notification = (RawNotification)taskInstance.TriggerDetails;
            string content = notification.Content;

            // ...
        }        
    }
}

Se você executar qualquer código assíncrono na tarefa em segundo plano, será necessário usar um deferral. Sem um adiamento, o processo da tarefa em segundo plano poderá ser encerrado de forma inesperada se o método Run for concluído antes do método assíncrono.

Solicite o adiamento no método Run antes de chamar o método assíncrono. Salve o adiamento em uma variável global, de modo que ele possa ser acessado a partir do método assíncrono. Declare o adiamento como concluído após a conclusão do código assíncrono. O código a seguir demonstra essas etapas usando um método assíncrono nomeado ExampleMethodAsync. Os comentários "// ..." serão substituídos pelo seu código que funciona em segundo plano.

Observação  Em C#, os métodos assíncronos da tarefa em segundo plano podem ser chamados usando as palavras-chave "async" ou "await". Em C++, é possível obter um resultado parecido usando uma cadeia de tarefas.

Para saber mais sobre padrões assíncronos nos aplicativos da Windows Store, veja Programação assíncrona. Para exemplos adicionais do uso de adiamentos para evitar que uma tarefa em segundo plano seja encerrada antes do esperado, veja o exemplo de tarefa em segundo plano.



public async void Run(IBackgroundTaskInstance taskInstance)
{
    BackgroundTaskDeferral _deferral = taskInstance.GetDeferral();
    
    RawNotification notification = (RawNotification)taskInstance.TriggerDetails;
    string content = notification.Content;

    // ...

    // Insert code to start one or more asynchronous methods using the "await" keyword.
    var result = await ExampleMethodAsync();
    
    // ...
    
    _deferral.Complete();
}

2. Declare a tarefa em segundo plano no manifesto do aplicativo.

Observação  Como pré-requisito para esta etapa, o aplicativo deve selecionar uma opção de tela de bloqueio e fornecer um logotipo de notificação antes de oferecer suporte a tarefas em segundo plano. Para saber mais, veja Guia de início rápido: mostrando as atualizações de bloco e notificação na tela de bloqueio.

Para o aplicativo registrar uma tarefa em segundo plano, você deve declarar a tarefa em segundo plano e seu gatilho no manifesto do aplicativo. Isso pode ser feito diretamente como XML ou pelo editor de manifesto do Microsoft Visual Studio.

  • Para usar o Editor de Manifesto, clique duas vezes no arquivo Package.appxmanifest do aplicativo no Visual Studio. Na guia Declarações, selecione Tarefas em Segundo Plano na lista suspensa Declarações Disponíveis. Como gatilho, selecione Notificação por push em Propriedades. Na caixa Página inicial, insira o nome do arquivo da tarefa em segundo plano (no nosso caso, ExampleBackgroundTask.cs).

    Se seu aplicativo usa mais de uma tarefa em segundo plano, repita esta etapa para cada tarefa, apontando cada vez para um arquivo diferente.

  • Para adicionar as informações diretamente ao XML do manifesto, abra o manifesto em um editor de texto. No elemento Extensions, adicione um elemento Extension para a classe de tarefa em segundo plano. O atributo Category deve ser definido como "windows.backgroundTasks" e o atributo StartPage deve nomear o arquivo da tarefa em segundo plano (em nosso caso, ExampleBackgroundTask.cs).

    Se seu aplicativo usa mais de uma tarefa em segundo plano, adicione um elemento Extension separado a cada tarefa, cada elemento apontando para um arquivo diferente.

    Você deve listar cada tipo de gatilho que uma tarefa em segundo plano usa. Como estamos criando uma tarefa em segundo plano que aciona uma resposta a uma notificação bruta, declararemos um gatilho de notificação por push. Adicione um elemento BackgroundTasks ao elemento Extension, com seu elemento Task definido como "pushNotification".

    O elemento Extension completo é mostrado aqui.



<Extension Category="windows.backgroundTasks" StartPage="js\examplebackgroundtask.js">
  <BackgroundTasks>
    <Task Type="pushNotification"/>
  </BackgroundTasks>
</Extension>

3. Registre a tarefa em segundo plano no aplicativo.

Os exemplos a seguir fornecem código que você adiciona ao seu aplicativo (por exemplo, no MainPage.xaml.cs file) para registrar a tarefa em segundo plano como resposta a uma notificação bruta.

Observação  Você também pode criar uma função dedicada ao registro de tarefa em segundo plano. Para saber mais, veja Como registrar uma tarefa em segundo plano. Nesse caso, em vez de usar as próximas etapas, você pode simplesmente construir o gatilho e oferecê-lo à função de registro junto com o nome da tarefa, o ponto de entrada da tarefa e (opcionalmente) uma condição.

Primeiro, determine se a tarefa em segundo plano já está registrada. Esta etapa é importante. Se o seu aplicativo não verificar se já existe um registro de tarefa em segundo plano, ele poderá registrar a mesma tarefa mais de uma vez. Isso pode causar problemas de desempenho e de uso da CPU que impeçam a conclusão da tarefa.

O seguinte exemplo itera por meio da propriedade Windows.ApplicationModel.Background.BackgroundTaskRegistration.AllTasks e define um sinalizador como true quando a tarefa já está registrada:



var taskRegistered = false;
var exampleTaskName = "ExampleBackgroundTask";

var iter = Windows.ApplicationModel.Background.BackgroundTaskRegistration.AllTasks.first();

while (iter.hasCurrent) {
    var task = iter.current.value;
    
    if (task.name == exampleTaskName) {
        taskRegistered = true;
        break;
    }

    iter.moveNext();
}

Se o aplicativo detectar que a tarefa em segundo plano não está registrada, ele poderá registrá-la chamando o método Windows.ApplicationModel.Background.BackgroundTaskBuilder.Register. Na chamada a esse método, você inclui o ponto de entrada da tarefa, que é o nome da classe da tarefa em segundo plano, prefixado com o namespace.

O gatilho da tarefa em segundo plano controla quando a tarefa em segundo plano será executada. Neste caso, usando um PushNotificationTrigger, ela será disparada quando uma notificação bruta for enviada ao canal de notificação por push.



if (!taskRegistered) {

var builder = new BackgroundTaskBuilder();

builder.Name = exampleTaskName;
builder.TaskEntryPoint = "Task.ExampleBackgroundTask";
builder.SetTrigger(new Windows.ApplicationModel.Background.PushNotificationTrigger());
BackgroundTaskRegistration task = builder.Register();
}

Resumo

Agora você já conhece os conceitos básicos sobre como criar uma classe de tarefa em segundo plano para usar com notificações brutas, incluindo como registrar a tarefa em segundo plano a partir do aplicativo. Você também deve entender como atualizar o manifesto do aplicativo, de modo que o Windows permita que o seu aplicativo registre as tarefas em segundo plano.

Observação  Você pode baixar a amostra de tarefa em segundo plano para ver esses exemplos de código e muito mais no contexto de um aplicativo da Windows Store completo e robusto que usa vários tipos diferentes de tarefas em segundo plano.

Tópicos relacionados

Exemplo de notificações brutas
Visão geral de notificações brutas
Diretrizes e lista de verificação para notificações brutas
Guia de início rápido: interceptando notificações por push para aplicativos em execução
RawNotification

 

 

Mostrar:
© 2014 Microsoft