Cómo usar el desencadenador ServicingComplete (HTML)

Artículo
12/12/2015

[ Este artículo está destinado a desarrolladores de Windows 8.x y Windows Phone 8.x que escriben aplicaciones de Windows en tiempo de ejecución. Si estás desarrollando para Windows 10, consulta la documentación más reciente

Aprende a usar el SystemTrigger ServicingComplete para controlar el registro de tareas en segundo plano después de las actualizaciones de la aplicación.

Lo que debes saber

Tecnologías

Windows.ApplicationModel.Background

Requisitos previos

Este tema es válido para todas las aplicaciones que ejecutan una o varias tareas en segundo plano. Encontrarás más información sobre cómo escribir una clase de tarea en segundo plano en Inicio rápido: crear y registrar una tarea en segundo plano.

Instrucciones

Paso 1: Crear una tarea en segundo plano ServicingComplete

Los registros de tareas en segundo plano se conservan de una actualización de la aplicación a otra. Si se actualiza una aplicación, sus registros continuarán siendo válidos y se desencadenarán. Una aplicación puede registrar una tarea en segundo plano con el desencadenador ServicingComplete que se notificará cuando se actualice la aplicación, y anular el registro de las tareas en segundo plano que ya no sean válidas.

Crea un nuevo archivo de JavaScript para la tarea en segundo plano.

El siguiente ejemplo de código muestra un punto de inicio básico para una tarea en 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();

})();

Encuentra el objeto de registro de la tarea en segundo plano que deseas anular. Llama a Unregister para anular el registro de la tarea. Ten en cuenta que puedes hacer que la tarea en segundo plano deje de ejecutarse (si hay una instancia activa) estableciendo el parámetro cancelTask en 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();

})();

Registra las tareas de reemplazo según corresponda. Usa una función de registro de tareas en segundo plano, como la que se especifica en Cómo registrar una tarea en segundo plano, para simplificar el trabajo.

//
// 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();

})();

Paso 2: Registrar la tarea en segundo plano ServicingComplete

La tarea en segundo plano ServicingComplete debe registrarse junto con otras tareas en segundo plano para que pueda desencadenarse cuando se actualice la aplicación. El punto de entrada de la tarea en segundo plano ServicingComplete debe ser el mismo en la actualización de la aplicación.

Crea un nuevo objeto SystemTrigger:
- El primer parámetro, triggerType, debe establecerse en servicingComplete.
- El segundo parámetro, OneShot, debe establecerse en false.
Este ejemplo de código crea un desencadenador ServicingComplete:
```
var background = Windows.ApplicationModel.Background;

var servicingCompleteTrigger = new background.SystemTrigger(
                        background.SystemTriggerType.servicingComplete, false);
```
Nota No se recomienda agregar una condición a un desencadenador de tarea en segundo plano ServicingComplete.
Llama a tu función de registro de tareas en segundo plano para registrar la tarea. Para obtener más información acerca del registro de tareas en segundo plano, consulta Cómo registrar una tarea en segundo plano.

El siguiente código registra la tarea ServicingComplete:
```
var entryPoint = "js\\ServicingCompleteTask.js";
var taskName = "ServicingComplete background task";

var task = RegisterBackgroundTask(entryPoint,
                                  taskName, 
                                  servicingCompleteTrigger, 
                                  null);
```
Nota En las aplicaciones de la Tienda de Windows Phone, debes llamar a RequestAccessAsync una vez antes de registrar cualquier tarea en segundo plano.

Paso 3: Declarar la tarea en segundo plano en el manifiesto de la aplicación

La tarea en segundo plano ServicingComplete debe enumerarse en el manifiesto de la aplicación, al igual que cualquier otra tarea en segundo plano. Para obtener más información, consulta Cómo declarar tareas en segundo plano en el manifiesto de la aplicación. Por ejemplo:

ServicingCompleteTask declarada en el manifiesto de la aplicación

Observaciones

Consulta Cómo depurar una tarea en segundo plano (aplicaciones de la Tienda Windows) para obtener información importante relacionada con la depuración de actualizaciones de aplicaciones con tareas en segundo plano.