Windows Dev Center

Idioma: HTML | XAML

Início rápido: criar e registrar uma tarefa em segundo plano (XAML)

Crie uma classe de tarefa em segundo plano e a registre para ser executada, fornecendo funcionalidade mesmo quando seu aplicativo não estiver em primeiro plano.

Pré-requisitos

  • Seu aplicativo precisa executar trabalho em segundo plano, e esse trabalho não pode ser executado com o uso de outra funcionalidade em segundo plano fornecida pela plataforma.

Criar a classe de Tarefa em segundo plano

Você pode executar código em segundo plano criando classes que implementam a interface IBackgroundTask. Esse código será executado quando um evento específico for acionado pelo uso de SystemTrigger ou MaintenanceTrigger por exemplo.

As seguintes etapas mostram como escrever uma nova classe que implementa a interface IBackgroundTask. Antes de iniciar, crie um novo projeto na sua solução para tarefas em segundo plano. Adicione uma nova classe vazia para a sua tarefa em segundo plano e importe o namespace Windows.ApplicationModel.Background.

  1. Crie um novo projeto para tarefas em segundo plano e adicione-o à sua solução. Para isso, clique com o botão direito na sua solução e selecione Adicionar->Novo projeto. Então, selecione o tipo de projeto Componente do Tempo de Execução do Windows, dê um nome ao projeto e clique em OK.
  2. Referencie o projeto de tarefa em segundo plano do seu aplicativo do projeto Windows Store ou Windows Phone.

    Para aplicativo em C++, clique com o botão direito do mouse no seu aplicativo de projeto e selecione Propriedades. Então, vá para Propriedades comuns e clique em Adicionar nova referência, marque a caixa de marcação próxima ao projeto de tarefa em segundo plano e clique em OK nas duas caixas de diálogo.

    Para um aplicativo C#, no seu projeto de aplicativo, clique com o botão direito em Referências e selecione Adicionar nova referência. Em Solução, selecione Projetos e clique para selecionar o nome do seu projeto de tarefa em segundo plano e clique em Ok.

  3. Crie uma nova classe que implemente a interface IBackgroundTask. O método Run é o ponto de entrada obrigatório que será chamado quando eventos específicos forem acionados. Este método é obrigatório em todas as tarefas em segundo plano.

    Observação  A classe de tarefa em segundo plano em si - e outras classes no projeto de tarefa em segundo plano - precisa ser de classes public que sejam sealed.

    O seguinte código de exemplo a seguir mostra um ponto inicial bem básico para uma classe de tarefa em segundo plano:

    
    
    //
    // ExampleBackgroundTask.cs
    //
    
    using Windows.ApplicationModel.Background;
    
    namespace Tasks
    {
        public sealed class ExampleBackgroundTask : IBackgroundTask
        {
            public void Run(IBackgroundTaskInstance taskInstance)
            {
                
            }        
        }
    }
    
    
    
    //
    // ExampleBackgroundTask.h
    //
    
    #pragma once
    
    using namespace Windows::ApplicationModel::Background;
    
    namespace Tasks
    {
        public ref class ExampleBackgroundTask sealed : public IBackgroundTask
        {
    
        public:
            ExampleBackgroundTask();
    
            virtual void Run(IBackgroundTaskInstance^ taskInstance);
            void OnCompleted(
                    BackgroundTaskRegistration^ task,
                    BackgroundTaskCompletedEventArgs^ args
                    );
        };
    }
    
    
  4. Se você executar um código assíncrono na sua tarefa em segundo plano, então ela precisará usar um adiamento. Se você não usar um adiamento, o processo da tarefa em segundo plano poderá ser encerrado de forma inesperada se o método Executar for concluído antes de a chamada de método assíncrona ser concluída.

    Solicite o adiamento no método Executar antes de chamar o método assíncrono. Salve o adiamento em uma variável global para que seja 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 seguinte exemplo de código obtém um adiamento, salva-o e o libera quando o código assíncrono é concluído:

    
    
    public async void Run(IBackgroundTaskInstance taskInstance)
    {
        BackgroundTaskDeferral _deferral = taskInstance.GetDeferral();
        
        //
        // TODO: Insert code to start one or more asynchronous methods using the
        //       await keyword, for example:
        //
        // await ExampleMethodAsync();
        //
        
        _deferral.Complete();
    }
    
    
    Observação  Em C#, os métodos assíncronos da tarefa em segundo plano podem ser chamados usando as palavras-chave async/await. Em C++, é possível obter um resultado parecido usando uma cadeia de tarefas.

    Para mais informações sobre padrões assíncronos, consulte Programação assíncrona. Para exemplos adicionais sobre como usar os adiamentos para evitar que uma tarefa em segundo plano pare antecipadamente, consulte a exemplo de tarefa em segundo plano.

O procedimento abaixo é concluído em uma de suas classes de aplicativo (por exemplo, MainPage.xaml.cs).

Observação  Você também pode criar uma função dedicada a registrar tarefas em segundo plano - veja Como registrar uma tarefa em segundo plano. Nesse caso, em vez de usar as próximas três 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.

Registre a tarefa em segundo plano a ser executada

  1. Veja se a tarefa em segundo plano já está registrada iterando através da propriedade BackgroundTaskRegistration.AllTasks. Esta etapa é importante; se seu aplicativo não verificar a existência de registros de tarefas em segundo plano, ele poderá facilmente registrar a tarefa várias vezes, causando problemas de desempenho e extrapolando o tempo de CPU disponível para a tarefa antes que esta possa ser concluída.

    O seguinte exemplo itera na propriedade AllTasks e define uma variável de sinalização para true se a tarefa já tiver sido registrada:

    
    var taskRegistered = false;
    var exampleTaskName = "ExampleBackgroundTask";
    
    foreach (var task in Background.BackgroundTaskRegistration.AllTasks)
    {
        if (task.Value.Name == exampleTaskName)
        {
            taskRegistered = true;
            break;
        }
    }
    
    
  2. Se a tarefa em segundo plano já não estiver registrada, use BackgroundTaskBuilder para criar uma instância de sua tarefa em segundo plano. O ponto de entrada da tarefa deve ser o nome de sua classe de tarefa em segundo plano prefixada pelo namespace.

    O gatilho da tarefa em segundo plano controla quando a tarefa será executada. Para obter uma lista dos possíveis gatilhos, veja SystemTrigger.

    Por exemplo, este código cria uma nova tarefa em segundo plano e define-a para ser executada quando o gatilho TimeZoneChanged é disparado:

    
    
    var builder = new BackgroundTaskBuilder();
    
    builder.Name = exampleTaskName;
    builder.TaskEntryPoint = "Tasks.ExampleBackgroundTask";
    builder.SetTrigger(new SystemTrigger(SystemTriggerType.TimeZoneChange, false));
    
    
  3. Você pode adicionar uma condição para controlar quando sua tarefa será executada após a ocorrência de um evento de gatilho (opcional). Por exemplo, se você não quiser que a tarefa seja executada até que o usuário esteja presente, use a condição UserPresent. Para obter uma lista das possíveis condições, veja SystemConditionType.

    O código de exemplo abaixo atribui uma condição que exige que o usuário esteja presente:

    
    builder.AddCondition(new SystemCondition(SystemConditionType.UserPresent));
    
    
  4. Registre a tarefa em segundo plano chamando o método Register no objeto BackgroundTaskBuilder. Armazene o resultado BackgroundTaskRegistration para que ele possa ser usado na próxima etapa.

    O código a seguir registra a tarefa em segundo plano e armazena o resultado:

    
    BackgroundTaskRegistration task = builder.Register();
    
    

    Observação  

    Para os aplicativos da Loja do Windows Phone, você deve chamar RequestAccessAsync antes de tentar registrar qualquer tarefa em segundo plano. No Windows, essa chamada é necessária somente para configurar tarefas em segundo plano que podem ser executadas somente se seu aplicativo estiver na tela de bloqueio, mas no telefone você deve chamar esse método uma vez para poder registrar qualquer tarefa em segundo plano.

    Para garantir que seu aplicativo da Loja do Windows Phone continue a ser executado corretamente depois que você liberar uma atualização, chame RemoveAccess e, em seguida, chame RequestAccessAsync quando seu aplicativo for iniciado após a atualização. Para saber mais, consulte Diretrizes para tarefas em segundo plano (aplicativos do Tempo de Execução do Windows).

    Observação  

    A partir do Windows 8.1, os parâmetros de registro de tarefas de segundo plano são validados no momento do registro. Um erro será retornado se algum parâmetro de registro for inválido. Seu aplicativo deve ser capaz de manipular cenários em que o registro de tarefas de segundo plano apresenta falha - por exemplo, use uma instrução condicional para verificar se há erros de registro e tente novamente o registro com falha usando valores de parâmetros diferentes.

Manipular a conclusão da tarefa em segundo plano usando manipuladores de eventos

Registre um método com o BackgroundTaskCompletedEventHandler, dessa forma seu aplicativo poderá obter resultados da tarefa em segundo plano. Quando o aplicativo for iniciado ou retomado, o método OnCompleted será chamado se a tarefa em segundo plano tiver sido concluída, desde a última vez que o aplicativo estava em primeiro plano. (O método OnCompleted será chamado imediatamente se a tarefa em segundo plano for concluída enquanto o aplicativo estiver em primeiro plano.)

  1. Escreva um método OnCompleted para manipular a conclusão das tarefas em segundo plano. Por exemplo, o resultado da tarefa em segundo plano pode ocasionar uma atualização da interface do usuário. O volume do método mostrado aqui é necessário para o método do manipulador de eventos OnCompleted, mesmo que este exemplo não use o parâmetro args.

    O seguinte código de exemplo reconhece a conclusão da tarefa em segundo plano e chama um método de atualização de interface de usuário de exemplo que leva a cadeia de caracteres da mensagem.

    
    
    private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
    {
        var settings = ApplicationData.Current.LocalSettings;
        var key = task.TaskId.ToString();
        var message = settings.Values[key].ToString();
        UpdateUIExampleMethod(message);
    }
    
    
    Observação  As atualizações da interface do usuário devem ser executadas assincronamente para evitar atraso do thread da interface do usuário. Por exemplo, veja o método UpdateUI no exemplo de tarefa em segundo plano.
  2. Retorne para onde você registrou a tarefa em segundo plano. Depois dessa linha de código, adicione um novo objeto BackgroundTaskCompletedEventHandler. Forneça o método OnCompleted como o parâmetro para o construtor BackgroundTaskCompletedEventHandler.

    O seguinte código de exemplo adiciona um BackgroundTaskCompletedEventHandler o BackgroundTaskRegistration:

    
    
    task.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);
    
    

Declarar que o seu aplicativo usa tarefas em segundo plano no manifesto do aplicativo

Antes de o seu aplicativo conseguir executar tarefas em segundo plano, você deve declarar cada tarefa em segundo plano no manifesto do aplicativo.

  • Abra o manifesto do aplicativo (o arquivo nomeado "package.appmanifest") e vá para o elemento Extensões. Adicione um elemento Extensões, com a categoria definida como "windows.backgroundTasks", para cada tarefa em segundo plano usada em seu aplicativo.

    Você deve listar cada tipo de disparador usado com a tarefa em segundo plano. Se o aplicativo tentar registrar uma tarefa em segundo plano com um disparador que não esteja listado no manifesto, o registro falhará.

    O seguinte elemento de exemplo de Extensões registra a tarefa em segundo plano criada neste tópico:

    
    
    <Extensions>
      <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ExampleBackgroundTask">
        <BackgroundTasks>
          <Task Type="systemEvent" />
        </BackgroundTasks>
      </Extension>
    </Extensions>
    
    

Resumo

Agora você deve compreender os fundamentos de como escrever uma classe de tarefa em segundo plano, como registrar a tarefa em segundo plano no aplicativo e como fazer o aplicativo reconhecer quando a tarefa em segundo plano é concluída. Você também deve saber atualizar o manifesto do aplicativo para que o Windows 8 permita que o aplicativo registre a tarefa em segundo plano.

Observação  Baixe o exemplo de tarefa em segundo plano para ver exemplos de código semelhantes, no contexto de um aplicativo da Windows Store completo e robusto, que usa tarefas em segundo plano.

Veja os seguintes tópicos relacionados para obter referência de API, diretriz conceitual de tarefa em segundo plano e instruções mais detalhadas para escrever aplicativos que usam tarefas em segundo plano.

Tópicos relacionados

Tópicos de instruções detalhadas de tarefa em segundo plano
Como responder a eventos do sistema com tarefas em segundo plano
Como registrar uma tarefa em segundo plano
Como definir condições para execução de uma tarefa em segundo plano
Quando usar os disparadores de manutenção
Como manipular uma tarefa em segundo plano cancelada
Como monitorar progresso e conclusão de tarefas em segundo plano
Como executar uma tarefa em segundo plano em um temporizador
Diretriz de tarefa em segundo plano
Diretrizes e listas de verificação para tarefas em segundo plano
How to debug a background task
Como disparar eventos de suspensão, retomada e segundo plano em aplicativos da Windows Store (durante a depuração)
Referência de API de tarefa em segundo plano
Windows.ApplicationModel.Background

 

 

Mostrar:
© 2015 Microsoft