Como usar o gatilho ServicingComplete (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]

Aprenda a usar ServicingComplete SystemTrigger para controlar o registro de tarefas em segundo plano depois de atualizações de aplicativos.

O que você precisa saber

Tecnologias

Windows.ApplicationModel.Background

Pré-requisitos

Este tópico se aplica a qualquer aplicativo que esteja executando uma ou mais tarefas em segundo plano. Para saber mais sobre como criar uma classe de tarefa em segundo plano, veja Guia de início rápido: criar e registrar uma tarefa em segundo plano.

Instruções

Etapa 1: Criar uma tarefa em segundo plano ServicingComplete

Registros de tarefas em segundo plano persistem em atualizações de aplicativos. Se um aplicativo for atualizado, seus registros continuarão a ser válidos e serão disparados. Um aplicativo pode registrar tarefas em segundo plano com o gatilho ServicingComplete para receber notificações quando for atualizado e também pode cancelar o registro de tarefas em segundo que perderam a validade.

Crie um novo arquivo JavaScript para a tarefa em segundo plano.

O código de amostra a seguir mostra um ponto de partida básica para uma tarefa em segundo plano:

//
// ServicingCompleteTask.js
//
(function () {
    "use strict";


    //
    // This function does the work of the ServicingComplete background task.
    //
    function doWork() {


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


    doWork();

})();

Encontre o objeto de registro para a tarefa em segundo plano cujo registro precisa ser cancelado. Chame Unregister para cancelar o registro da tarefa. Observe que você pode forçar a tarefa em segundo plano a interromper sua execução (se uma instância estiver ativa) definindo o parâmetro cancelTask como true.

//
// ServicingCompleteTask.js
//
(function () {
    "use strict";


    //
    // This function does the work of the ServicingComplete background task.
    //
    function doWork() {

        // 
        // Unregister tasks that no longer exist.
        // 

        var unregisterTask = "BadTaskName";

        var unregTask = FindTask(unregisterTask);
        if (unregTask != null) {
            unregTask.Unregister(true);
        }


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


    // 
    // Check for a registration of the named background task. If one exists,
    // return it.
    // 
    function FindTask(taskName) {

        var taskRegistered = false;

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

        while (hascur) {
            var cur = iter.current.value;

            if (cur.name === taskName) {
                return cur;
            }

            hascur = iter.moveNext();
        }
    }


    doWork();

})();

Registre tarefas de substituição conforme apropriado. Use uma função de registro de tarefa em segundo plano, como aquela especificada em Como registrar uma tarefa em segundo plano, para simplificar o trabalho.

//
// ServicingCompleteTask.js
//
(function () {
    "use strict";


    //
    // This function does the work of the ServicingComplete background task.
    //
    function doWork() {

        // 
        // Unregister tasks that no longer exist.
        // 

        var unregisterTask = "BadTaskName";

        var unregTask = FindTask(unregisterTask);
        if (unregTask != null) {
            unregTask.Unregister(true);
        }


        // 
        // Register new/replacement tasks.
        // 

        var newTaskName = "New Background Task";
        var newTaskEntryPoint = "js\\NewBackgroundTask.js";

        var background = Windows.ApplicationModel.Background;
        var internetTrigger = new background.SystemTrigger(
                         background.SystemTriggerType.internetAvailable, false);

        var newTask = RegisterBackgroundTask(newTaskEntryPoint,
                                             newTaskName, 
                                             internetTrigger, 
                                             null);


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


    // 
    // Check for a registration of the named background task. If one exists,
    // return it.
    // 
    function FindTask(taskName) {

        var taskRegistered = false;

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

        while (hascur) {
            var cur = iter.current.value;

            if (cur.name === taskName) {
                return cur;
            }

            hascur = iter.moveNext();
        }
    }


    doWork();

})();

Etapa 2: Registrar a tarefa em segundo plano ServicingComplete

A tarefa em segundo plano ServicingComplete deve ser registrada junto com outras tarefas em segundo plano. Dessa forma, ela pode ser disparada quando o aplicativo for atualizado. O ponto de entrada para a tarefa em segundo plano ServicingComplete deve permanecer o mesmo na atualização do aplicativo.

Crie um novo objeto SystemTrigger:
- O primeiro parâmetro, triggerType, deve ser definido como servicingComplete.
- O segundo parâmetro, OneShot, deve ser definido como false.
Este código de exemplo cria um gatilho ServicingComplete:
```
var background = Windows.ApplicationModel.Background;

var servicingCompleteTrigger = new background.SystemTrigger(
                        background.SystemTriggerType.servicingComplete, false);
```
Observação Não é recomendável adicionar uma condição a um gatilho de tarefa em segundo plano ServicingComplete.
Chame sua função de registro de tarefa em segundo plano para registrar a tarefa. Para saber mais sobre o registro de tarefas em segundo plano, veja Como registrar uma tarefa em segundo plano.

O código a seguir registra a tarefa em segundo plano ServicingComplete:
```
var entryPoint = "js\\ServicingCompleteTask.js";
var taskName = "ServicingComplete background task";

var task = RegisterBackgroundTask(entryPoint,
                                  taskName, 
                                  servicingCompleteTrigger, 
                                  null);
```
Observação Nos aplicativos da Loja do Windows Phone, você deve chamar RequestAccessAsync antes de registrar qualquer tarefa em segundo plano.

Etapa 3: Declarar a tarefa em segundo plano no manifesto do aplicativo

A tarefa em segundo plano ServicingComplete precisa estar listada no manifesto do pacote, igual a qualquer outra tarefa em segundo plano. Para saber mais, veja Como declarar tarefas em segundo plano no manifesto do aplicativo. Por exemplo:

ServicingCompleteTask declarada no manifesto do aplicativo

Comentários

Veja Como depurar uma tarefa em segundo plano (aplicativos da Windows Store) para obter informações importantes relacionadas à depuração de atualizações de aplicativos com tarefas em segundo plano.