Démarrage rapide : créer et inscrire une tâche en arrière-plan (HTML)

Article
12/11/2015

[ Cet article est destiné aux développeurs de Windows 8.x et Windows Phone 8.x qui créent des applications Windows Runtime. Si vous développez une application pour Windows 10, voir la Documentation ]

Cette rubrique explique comment créer et inscrire une tâche en arrière-plan pour votre application.

Prérequis

Développez une application prête à fournir une tâche en arrière-plan.

Créer la classe de tâche en arrière-plan

Créez une méthode distincte avec le code qui s’exécute en arrière-plan. Ce code s’exécute lorsqu’un événement spécifique est déclenché. Lisez SystemTrigger et MaintenanceTrigger pour obtenir la liste des types de déclencheurs qui peuvent être utilisés par une application.

Les étapes qui suivent expliquent comment écrire une tâche en arrière-plan qui utilise Windows.UI.WebUI.WebUIBackgroundTaskInstance. Avant de commencer, créez un fichier JavaScript vide dans Microsoft Visual Studio.

Créez un fichier JavaScript dans votre projet. Les fonctions et le code inclus dans ce fichier constituent les éléments qui seront exécutés en arrière-plan.

La structure de code suivante peut vous aider à démarrer :


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

})();

Une tâche en arrière-plan doit être capable de reconnaître quand vous lui demandez d’arrêter son travail. Avant tout, ajoutez un écouteur d’événements pour l’événement « canceled », puis ajoutez une variable appelée « canceled » pour signaler la tâche en arrière-plan.

L’exemple de tâche en arrière-plan écoute l’événement « canceled » à l’aide des fonctions onCanceled :

    var cancel = false;

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

Modifiez ensuite votre code pour arrêter votre travail et fermer si l’événement canceled a la valeur True.

L’exemple de tâche en arrière-plan crée une tâche appelée 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();
    }

})();

Assurez-vous que votre tâche en arrière-plan appelle la méthode close() intégrée chaque fois qu’elle mène son travail à terme ou est annulée. Si la tâche en arrière-plan ne se ferme pas d’elle-même, son processus peut perdurer et risque de consommer de la mémoire et de réduire l’autonomie de la batterie même si la tâche en arrière-plan est terminée.

Appelez la méthode close() chaque fois qu’une tâche en arrière-plan JavaScript s’exécute à terme ou est annulée :
```
close();
```

Dans les étapes qui suivent, vous devez ajouter du code à votre application existante (par exemple, « default.js »).

Remarque Vous pouvez aussi créer une fonction consacrée à l’inscription des tâches en arrière-plan (voir Comment inscrire une tâche en arrière-plan). Dans ce cas, plutôt que de suivre les trois étapes suivantes, vous pouvez simplement construire le déclencheur et le communiquer à la fonction d’inscription avec le nom de la tâche, son point d’entrée et une condition (facultatif).

Inscrire la tâche en arrière-plan

Découvrez si la tâche en arrière-plan est déjà inscrite en parcourant la propriété BackgroundTaskRegistration.allTasks. Cette étape est primordiale ; si votre application ne vérifie pas la présence d’inscriptions de tâches en arrière-plan existantes, elle peut aisément procéder plusieurs fois à l’inscription de la tâche, ce qui risque de poser des problèmes de performance et d’épuiser le temps processeur disponible pour la tâche avant que le travail ne soit effectué.

L’exemple qui suit parcourt la propriété allTasks et définit une variable d’indicateur sur true si la tâche est déjà inscrite :
```
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 elle n’est pas déjà inscrite, inscrivez-la en appelant la fonction register et en transmettant le nom de fichier de la tâche en arrière-plan et un élément SystemTrigger.

Le déclencheur de tâche en arrière-plan contrôle à quel moment la tâche en arrière-plan. Voir SystemTrigger pour obtenir une liste des déclencheurs système possibles.


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

Vous pouvez ajouter une condition afin de contrôler à quel moment votre tâche sera exécutée après que l’événement de déclencheur est survenu (facultatif). Par exemple, si vous ne souhaitez pas que la tâche s’exécute tant que l’utilisateur n’est pas présent, appliquez la condition UserPresent. Pour obtenir la liste des conditions possibles, voir SystemConditionType.

Remarque

À compter de Windows 8.1, les paramètres d’inscription de la tâche en arrière-plan sont validés au moment de l’inscription. Une erreur est retournée si l’un des paramètres d’inscription n’est pas valide. Votre application doit être en mesure de gérer les scénarios dans lesquels l’inscription de la tâche en arrière-plan échoue. Par exemple utilisez une instruction conditionnelle pour rechercher les erreurs d’inscription, puis retentez l’inscription qui a échoué avec d’autres valeurs de paramètres.
```
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();
}
```
Remarque

Dans les applications du Windows Phone Store, vous devez appeler RequestAccessAsync avant d’essayer d’inscrire une tâche en arrière-plan. Sur Windows, cet appel est requis uniquement pour l’ensemble de tâches en arrière-plan pour lesquelles votre application doit être sur l’écran de verrouillage afin de s’exécuter, mais sur un téléphone, vous devez appeler cette méthode une fois avant d’inscrire une tâche en arrière-plan.

Pour vous assurer que votre application Windows Phone continue de s’exécuter correctement après la publication d’une mise à jour, vous devez appeler RemoveAccess, puis RequestAccessAsync lorsque votre application est lancée après avoir été mise à jour. Pour plus d’informations, voir Recommandations relatives aux tâches en arrière-plan (HTML).

Gérer l’exécution à terme des tâches en arrière-plan

Votre application peut suivre la progression et la réalisation à terme de la tâche en arrière-plan en l’inscrivant pour l’écouteur d’événements « completed » chaque fois que l’application est activée.

Écrivez une fonction que votre application peut utiliser pour savoir quand une tâche en arrière-plan est terminée.

L’exemple de tâche en arrière-plan ajoute une fonction appelée 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");
        }
    };
}

Abonnez-vous à l’écouteur d’événements « completed » avec la fonction.

L’exemple de tâche en arrière-plan ajoute onCompleted à l’événement « completed » :
```
task.addEventListener("completed", new BackgroundTaskSample.completeHandler(task).onCompleted);
```

Déclarer que votre application utilise des tâches en arrière-plan dans le manifeste de l’application

Avant que votre application ne puisse exécuter des tâches en arrière-plan, vous devez déclarer chaque tâche en arrière-plan (et le déclencheur qu’elle utilise) dans le manifeste de l’application.

Ouvrez le manifeste de l’application et accédez à l’élément Extensions. Ajoutez un élément Extension, avec la catégorie définie sur "windows.backgroundTasks", pour chaque classe de tâche en arrière-plan utilisée dans votre application. Vous devez répertorier chaque type de déclencheur que la tâche en arrière-plan utilise. Votre application ne sera pas capable d’inscrire la tâche en arrière-plan avec un type de déclencheur non déclaré.

L’exemple de tâche en arrière-plan inscrit trois tâches en arrière-plan :
```
<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>
```

Récapitulatif

Vous devez à présent être en mesure d’écrire une classe de tâche en arrière-plan, d’inscrire la tâche en arrière-plan dans votre application et de permettre à votre application de reconnaître à quel moment la tâche en arrière-plan est achevée. Vous devez également savoir comment mettre à jour le manifeste de l’application de sorte que le système d’exploitation autorise votre application à inscrire les tâches en arrière-plan.

Remarque Vous pouvez télécharger l’exemple de tâche en arrière-plan pour examiner les exemples de code (et plus encore) disponibles dans le contexte d’une application JavaScript aboutie et robuste ayant recours à des tâches en arrière-plan.