Guia de início rápido: criar e registrar uma tarefa em segundo plano (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Este tópico discute como criar e registrar um trabalho de tarefa em segundo plano para o seu aplicativo.

Pré-requisitos

Faça com que um aplicativo pronto forneça uma tarefa em segundo plano.

Criar a classe de Tarefa em Segundo Plano

Crie um método separado com o código executado em segundo plano. Esse código será executado quando um evento específico for disparado. Leia SystemTrigger e MaintenanceTrigger para obter uma lista de tipos de gatilho que podem ser usados por outro aplicativo.

As etapas a seguir mostram como gravar um trabalhador de tarefa em segundo plano que utiliza Windows.UI.WebUI.WebUIBackgroundTaskInstance. Antes de iniciar, crie um novo arquivo JavaScript vazio em Microsoft Visual Studio.

Crie um novo arquivo JavaScript em seu projeto. As funções e código nesse arquivo são os que executarão em segundo plano.

O código esqueleto a seguir pode ajudar você a iniciar:


//
// A JavaScript background task is specified in a .js file. The name of the file is used to
// launch the background task.
//
(function () {
    "use strict";

    //
    // This var is used to get information about the current instance of the background task.
    //
    var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;


    //
    // This function will do the work of your background task.
    //
    function doWork() {
        var key = null,
            settings = Windows.Storage.ApplicationData.current.localSettings;

        // Write JavaScript code here to do work in the background.


        //
        // Record information in LocalSettings to communicate with the app.
        //
        key = backgroundTaskInstance.task.taskId.toString();
        settings.values[key] = "Succeeded";

        //
        // A JavaScript background task must call close when it is done.
        //
        close();
    }

    doWork();

})();

Uma tarefa em segundo plano deve reconhecer quando há uma solicitação de parar o trabalho. Primeiro, adicione um ouvinte para o evento "cancelado" e adicione uma variável denominada "cancelada" para sinalizar a tarefa em segundo plano.

A amostra de tarefa em segundo plano atende ao evento "cancelado" com funções onCanceled:

    var cancel = false;

    //
    // Associate a cancellation handler with the background task.
    //
    function onCanceled(cancelSender, cancelReason) {
        cancel = true;
    }
    backgroundTaskInstance.addEventListener("canceled", onCanceled);

Em seguida, modifique seu código para parar e fechar se cancelado for definido para verdade.

A amostra de tarefa em segundo plano cria uma tarefa chamada SampleBackgroundTask:


//
// A JavaScript background task is specified in a .js file. The name of the file is used to
// launch the background task.
//
(function () {
    "use strict";

    //
    // This var is used to get information about the current instance of the background task.
    //
    var backgroundTaskInstance = Windows.UI.WebUI.WebUIBackgroundTaskInstance.current;


    //
    // This function will do the work of your background task.
    //
    function doWork() {
        var key = null,
            settings = Windows.Storage.ApplicationData.current.localSettings;

        //
        // TODO: Write your JavaScript code here to do work in the background.
        // If you write a loop or callback, remember  have it check for canceled==false.
        //

        //
        // Record information in LocalSettings to communicate with the app.
        //
        key = backgroundTaskInstance.task.taskId.toString();
        settings.values[key] = "Succeeded";

        //
        // A JavaScript background task must call close when it is done.
        //
        close();
    }

    if (!canceled) {
        doWork();
    } else {
        //
        // Record information in LocalSettings to communicate with the app.
        //
        key = backgroundTaskInstance.task.taskId.toString();
        settings.values[key] = "Canceled";

        //
        // A JavaScript background task must call close when it is done.
        //
        close();
    }

})();

Assegure que sua tarefa em segundo plano chame o método close() integrado cada vez que ela concluir o trabalho ou for cancelada. Se a tarefa em segundo plano não fechar sozinha, o processo da tarefa em segundo plano poderá continuar existindo, consumindo memória e bateria, mesmo que a tarefa em segundo plano tenha sido concluída.

Chame close() sempre que uma tarefa em segundo plano JavaScript concluir o trabalho ou for cancelada:
```
close();
```

O seguinte procedimento envolve a inclusão de código ao seu aplicativo existente (por exemplo, "default.js").

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.

Registrar a tarefa em segundo plano

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 = "Example background task worker name";

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

while (iter.hasCurrent) {

    var task = iter.current.value;

    if (task.name === exampleTaskName) {

        taskRegistered = true;
        break;
    }

    iter.moveNext();
}
```

Se ela não tiver sido registrada, registre a tarefa em segundo plano chamando a função register, passando no nome de arquivo da tarefa em segundo plano e um SystemTrigger.

O gatilho da tarefa em segundo plano controla quando a tarefa será executada. Veja SystemTrigger para obter uma lista de possíveis gatilhos do sistema.


if (taskRegistered != true) {

    var builder = new Windows.ApplicationModel.Background.BackgroundTaskBuilder();

    var trigger = new Windows.ApplicationModel.Background.SystemTrigger(Windows.ApplicationModel.Background.SystemTriggerType.timeZoneChange, false);

    builder.name = exampleTaskName;
    builder.taskEntryPoint = "js\\ExampleBackgroundTask.js";
    builder.setTrigger(trigger);

    var task = builder.register();
}

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.

Observação

A partir do Windows 8.1, os parâmetros de registro de tarefas em 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.
```
if (taskRegistered != true) {

    var builder = new Windows.ApplicationModel.Background.BackgroundTaskBuilder();

    var trigger = new Windows.ApplicationModel.Background.SystemTrigger(Windows.ApplicationModel.Background.SystemTriggerType.timeZoneChange, false);

    builder.name = exampleTaskName;
    builder.taskEntryPoint = "js\\ExampleBackgroundTask.js";
    builder.setTrigger(trigger);

    builder.addCondition(new Windows.ApplicationModel.Background.SystemCondition(Windows.ApplicationModel.Background.SystemConditionType.userPresent));

    var 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 executar 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 do Windows Phone continua 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 (HTML).

Manipular a conclusão da tarefa em segundo plano

O seu aplicativo pode observar o progresso e a conclusão do trabalho da tarefa em segundo plano registrando para o ouvinte de eventos "concluídos".

Greve uma função que o seu aplicativo pode usar para reconhecer a conclusão do trabalho em segundo plano.

O exemplo de tarefa em segundo plano adiciona uma função chamada onCompleted:


//
// Handle background task completion.
//
"completeHandler": function (task) {
    this.onCompleted = function (args) {
        try {
            var key = task.taskId;
            var settings = Windows.Storage.ApplicationData.current.localSettings;
            var status = settings.values[key];

            switch (task.name) {
                case BackgroundTaskSample.sampleBackgroundTaskName:
                    BackgroundTaskSample.sampleBackgroundTaskStatus = status;
                    SampleBackgroundTask.updateUI();
                    break;
                case BackgroundTaskSample.sampleBackgroundTaskWithConditionName:
                    BackgroundTaskSample.sampleBackgroundTaskWithConditionStatus = status;
                    SampleBackgroundTaskWithCondition.updateUI();
                    break;
                case BackgroundTaskSample.servicingCompleteTaskName:
                    BackgroundTaskSample.servicingCompleteTaskStatus = status;
                    ServicingComplete.updateUI();
                    break;
                case BackgroundTaskSample.javaScriptBackgroundTaskName:
                    BackgroundTaskSample.javaScriptBackgroundTaskStatus = status;
                    JavaScriptBackgroundTask.updateUI();
                    break;
                case BackgroundTaskSample.timeTriggerTaskName:
                    BackgroundTaskSample.timeTriggerTaskStatus = status;
                    TimeTriggerBackgroundTask.updateUI();
                    break;
            }
        } catch (ex) {
            //WinJS.log && WinJS.log(ex, "sample", "status");
        }
    };
}

Assine o ouvinte de eventos "concluídos" com a função.

O exemplo de tarefa em segundo plano adiciona onCompleted ao evento "concluído":
```
task.addEventListener("completed", new BackgroundTaskSample.completeHandler(task).onCompleted);
```

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

Antes que o seu aplicativo pode registrar tarefas em segundo plano, você deve declarar cada tarefa em segundo plano (e os gatilhos que ela usa) no manifesto do aplicativo.

Abra o manifesto do aplicativo 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 gatilho que a tarefa em segundo plano utiliza - seu aplicativo não será capaz de registrar a tarefa em segundo plano com um tipo de gatilho não declarado.

O exemplo de tarefa em segundo plano registrar três trabalhos de tarefa em segundo plano:


<Extension Category="windows.backgroundTasks" StartPage="js\backgroundtask.js">
  <BackgroundTasks>
    <Task Type="systemEvent" />
  </BackgroundTasks>
</Extension>
<Extension Category="windows.backgroundTasks" EntryPoint="Tasks.SampleBackgroundTask">
  <BackgroundTasks>
    <Task Type="systemEvent" />
    <Task Type="timer" />
  </BackgroundTasks>
</Extension>
<Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ServicingComplete">
  <BackgroundTasks>
    <Task Type="systemEvent" />
  </BackgroundTasks>
</Extension>

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 SO permita que o aplicativo registre a tarefa em segundo plano.

Observação Você pode baixar o exemplo de tarefa em segundo plano para ver esses exemplos de código (e muito mais) no contexto de um aplicativo JavaScript completo e robusto que usa tarefas em segundo plano.