Inicio rápido: Crear y registrar una tarea en segundo plano (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

En este tema se analiza cómo crear y registrar un trabajo de tarea en segundo plano para tu aplicación.

Requisitos previos

Tienes una aplicación lista para proporcionarle una tarea en segundo plano.

Crear la clase de tareas en segundo plano

Crea un método separado con el código que se ejecuta en segundo plano. Este código se ejecutará cuando se desencadene un evento específico. Lee SystemTrigger y MaintenanceTrigger para obtener una lista de tipos de desencadenadores que cualquier aplicación puede usar.

En los siguientes pasos te explicamos cómo escribir un trabajo de tarea en segundo plano que usa Windows.UI.WebUI.WebUIBackgroundTaskInstance. Antes de empezar, crea un archivo JavaScript vacío en Microsoft Visual Studio.

Crea un archivo JavaScript en el proyecto. Las funciones y código de este archivo será lo que se ejecute en segundo plano.

El siguiente código puede servirte para empezar:


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

})();

Una tarea en segundo plano debe reconocer el momento en el que se le pide que pare. Por lo tanto, antes de nada, vamos a agregar una escucha de evento para el evento "canceled" y agregaremos una variable llamada "canceled" que avise a la tarea en segundo plano.

La muestra de tarea en segundo plano escucha el evento "canceled" con las funciones onCanceled:

    var cancel = false;

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

A continuación, modifica el código de forma que detenga el trabajo y se cierre si "canceled" está establecido en true.

La muestra de tarea en segundo plano crea una tarea llamada 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();
    }

})();

Procura que la tarea en segundo plano llame al método integrado close() cada vez que finalice el trabajo o se cancele. Si la tarea en segundo plano no se cierra a sí misma, su proceso puede seguir existiendo, consumiendo memoria y duración de batería, incluso después de que la tarea en segundo plano se complete.

Llama a close() cada vez que una tarea en segundo plano de JavaScript finalice el trabajo o se cancele:
```
close();
```

Los pasos siguientes implican agregar código a tu aplicación existente (por ejemplo, "default.js").

Nota También puedes crear una función dedicada para registrar tareas en segundo plano; consulta Cómo registrar una tarea en segundo plano. En ese caso, en lugar de usar los siguientes 3 pasos, simplemente puedes construir el desencadenador y proporcionar la función de registro junto con el nombre de la tarea, el punto de entrada de la tarea y (de forma opcional) una condición.

Registrar la tarea en segundo plano

Averigua si la tarea en segundo plano ya está registrada al iterar en la propiedad BackgroundTaskRegistration.allTasks. Este paso es importante; si tu aplicación no comprueba los registros de tareas en segundo plano existentes, fácilmente podría registrar una tarea varias veces. Esto causaría problemas de rendimiento y consumiría el tiempo de CPU disponible para la tarea antes de que su trabajo pueda completarse.

El siguiente ejemplo itera en la propiedad allTasks y establece una variable de marca en true, si la tarea ya está 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();
}
```

Si aún no está registrada, registra la tarea en segundo plano llamando a la función register, pasando el nombre del archivo de la tarea en segundo plano y un SystemTrigger.

El desencadenador de tarea en segundo plano controla cuándo se ejecutará la tarea en segundo plano. Para obtener una lista de posibles desencadenadores del sistema, consulta SystemTrigger


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

Puedes agregar una condición para controlar si la tarea se ejecutará después de que se produzca el evento del desencadenador (opcional). Por ejemplo, si solo deseas que la tarea se ejecute cuando el usuario esté presente, usa la condición UserPresent. Para obtener una lista de posibles condiciones, consulta SystemConditionType.

Nota

A partir de Windows 8.1, los parámetros de registro de tareas en segundo plano se validan en el momento de realizar el registro. Se devuelve un error si cualquiera de los parámetros de registro no es válido. La aplicación debe poder enfrentarse a los escenarios en que se produce un error en el registro de tareas en segundo plano. Por ejemplo, usa una instrucción condicional para comprobar si hay errores de registro y después vuelve a probar el registro con errores con 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();
}
```
Nota

En las aplicaciones de la Tienda de Windows Phone, debes llamar a RequestAccessAsync antes de intentar registrar cualquier tarea en segundo plano. En Windows, esta llamada solo es necesaria para el conjunto de tareas en segundo plano que requieren que tu aplicación esté en la pantalla de bloqueo para ejecutarse, pero en el teléfono debes llamar a este método una vez antes de registrar cualquier tarea en segundo plano.

Para garantizar que la aplicación de Windows Phone continúe funcionando correctamente después de publicar una actualización, se debe llamar a RemoveAccess y luego a RequestAccessAsync cuando se inicia la aplicación tras su actualización. Para obtener más información, consulta Directrices para tareas en segundo plano (HTML).

Administrar la finalización de tareas en segundo plano

Tu aplicación puede controlar el progreso y la finalización de la tarea en segundo plano al registrarse para el agente de escucha de eventos "completed" cada vez que la aplicación se active.

Escribe una función que tu aplicación pueda usar para reconocer la finalización del trabajo en segundo plano.

La muestra de tarea en segundo plano agrega una función llamada 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");
        }
    };
}

Suscribirse al agente de escucha de eventos "completed" con la función.

La muestra de tarea en segundo plano agrega onCompleted al evento "completed":
```
task.addEventListener("completed", new BackgroundTaskSample.completeHandler(task).onCompleted);
```

Declarar que tu aplicación usa tareas en segundo plano en el manifiesto de la aplicación

Antes de que tu aplicación realmente pueda registrar tareas en segundo plano, debes declarar cada una de ellas (y los desencadenadores que usan) en el manifiesto de la aplicación.

Abre el manifiesto de la aplicación y ve al elemento Extensions. Agrega un elemento Extension, con la categoría establecida en "windows.backgroundTasks", para cada clase de tarea en segundo plano usada en tu aplicación. Debes incluir en una lista cada tipo de desencadenador con el que se use la tarea en segundo plano. Tu aplicación no podrá registrar las tareas en segundo plano con un desencadenador no declarado.

La muestra de tarea en segundo plano registra tres trabajos de tareas en 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>

Resumen

Ahora deberías conocer los conceptos básicos de cómo escribir una clase de tareas en segundo plano, cómo registrar la tarea en segundo plano desde dentro de tu aplicación y cómo hacer que tu aplicación reconozca cuándo se ha completado la tarea en segundo plano. También debes comprender cómo actualizar el manifiesto de la aplicación para que el sistema operativo permita que tu aplicación registre tareas en segundo plano.

Nota Puedes descargar la muestra de tarea en segundo plano para ver estos ejemplos de código (y otros) en el contexto de una aplicación JavaScript completa y sólida que utilice tareas en segundo plano.