Guida introduttiva: Creare e registrare un'attività in background (HTML)

Articolo
12/11/2015

[ Questo articolo è rivolto agli sviluppatori per Windows 8.x e Windows Phone 8.x che realizzano app di Windows Runtime. Gli sviluppatori che usano Windows 10 possono vedere Documentazione aggiornata ]

Questo argomento descrive come creare e registrare un processo di lavoro con attività in background per l'app.

Prerequisiti

Un'app per la quale creare un'attività in background.

Creare la classe attività in background

Crea un metodo separato con il codice eseguito in background. Questo codice verrà eseguito quando viene attivato un evento specifico. Leggi SystemTrigger e MaintenanceTrigger per l'elenco dei tipi di trigger che possono essere usati da qualsiasi app.

I passaggi seguenti illustrano come scrivere un worker di attività in background che usa l'interfaccia Windows.UI.WebUI.WebUIBackgroundTaskInstance. Prima di iniziare, crea un nuovo file JavaScript vuoto in Microsoft Visual Studio.

Crea un nuovo file JavaScript nel progetto. Le funzioni e il codice di questo file rappresentano la parte che verrà eseguita in background.

L'abbozzo di codice seguente ti sarà utile per iniziare.


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

})();

Un'attività in background deve riconoscere una richiesta di interruzione. Prima di tutto, aggiungi un listener di eventi per l'evento "canceled" e aggiungi una variabile "canceled" come segnale per l'attività in background.

L'esempio di attività in background ascolta l'evento "canceled" con le funzioni onCanceled:

    var cancel = false;

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

Quindi, modifica il tuo codice in modo che si interrompa e si chiuda se canceled è impostato su true.

L'esempio di attività in background crea un'attività denominata 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();
    }

})();

Assicurati che la tua attività in background chiami il metodo close() incorporato ogni volta che viene completata o annullata. Se l'attività in background non si chiude, il relativo processo può continuare a esistere, consumando memoria e durata della batteria anche se l'attività è terminata.

Chiama close() ogni volta che un'attività in background di JavaScript viene completata o annullata:
```
close();
```

I passaggi seguenti implicano l'aggiunta di codice all'app esistente, ad esempio "default.js".

Nota Puoi anche creare una funzione dedicata alla registrazione di attività in background (vedi Come registrare un'attività in background). In tal caso, anziché usare i prossimi 3 passaggi, puoi semplicemente creare il trigger e fornirlo alla funzione di registrazione insieme al nome dell'attività, al punto di ingresso e a una condizione (facoltativa).

Registrare l'attività in background

Verifica se l'attività in background è già stata registrata eseguendo un'iterazione tramite la proprietà BackgroundTaskRegistration.allTasks. Questo passaggio è importante poiché, se l'app non verifica la presenza di registrazioni esistenti dell'attività in background, può registrarla più volte, causando problemi di prestazioni ed esaurendo il tempo CPU disponibile per l'attività prima che possa essere completata.

L'esempio seguente illustra l'iterazione della proprietà allTasks e imposta una variabile flag su true se l'attività è già registrata:
```
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();
}
```

In caso contrario, registra l'attività in background chiamando la funzione register, passando il nome del file dell'attività in background e un SystemTrigger.

Il trigger dell'attività in background determina quando essa viene eseguita. Per un elenco dei possibili trigger di sistema, vedi 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();
}

Puoi aggiungere una condizione per determinare quando eseguire l'attività dopo che si verifica l'evento del trigger (facoltativo). Ad esempio, se non vuoi che l'attività venga eseguita finché l'utente è presente, usa la condizione UserPresent. Per l'elenco delle possibili condizioni, vedi SystemConditionType.

Nota

A partire da Windows 8.1, i parametri di registrazione dell'attività in background vengono convalidati al momento della registrazione. Se uno dei parametri di registrazione non è valido, viene restituito un errore. L'app deve essere in grado di gestire scenari in cui si verifica un errore di registrazione dell'attività in background. Puoi ad esempio usare un'istruzione condizionale per controllare la presenza di errori di registrazione e quindi eseguire un nuovo tentativo in caso di errore della registrazione usando valori dei parametri diversi.
```
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

Per le app di Windows Phone Store, devi chiamare RequestAccessAsync prima di tentare di registrare attività in background. In Windows la chiamata è necessaria solo per il set di attività in background per la cui esecuzione l'app deve essere nella schermata di blocco. Nel telefono devi tuttavia chiamare il metodo una volta prima di registrare attività in background.

Per garantire che l'app di Windows Phone continui a funzionare correttamente dopo il rilascio di un aggiornamento, devi chiamare RemoveAccess e poi chiamare RequestAccessAsync all'avvio dell'app dopo l'aggiornamento. Per altre informazioni, vedi Linee guida per le attività in background (HTML).

Gestire il completamento dell'attività in background

L'app può osservare lo stato e il completamento dell'attività in background effettuando la registrazione per il listener di eventi "completed" ogni volta che l'app viene attivata.

Scrivi una funzione utilizzabile dall'app per riconoscere il completamento del processo di lavoro in background.

L'esempio di attività in background aggiunge una funzione denominata 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");
        }
    };
}

Sottoscrivi il listener di eventi "completed" con la funzione.

L'esempio di attività in background aggiunge onCompleted all'evento "completed":
```
task.addEventListener("completed", new BackgroundTaskSample.completeHandler(task).onCompleted);
```

Dichiarare che l'app usa attività in background nel manifesto dell'app

Perché l'app possa effettivamente registrare le attività in background, devi dichiarare ogni attività in background, con i relativi trigger, nel manifesto dell'app.

Apri il manifesto dell'applicazione e passa all'elemento Extensions. Aggiungi un elemento Extension impostando la categoria su "windows.backgroundTasks" per ogni classe di attività in background utilizzata nell'app. Devi elencare ogni tipo di trigger usato dall'attività in background poiché l'app non può registrare l'attività in background con un tipo di trigger non dichiarato.

L'esempio di attività in background registra tre processi di lavoro con attività in background:


<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>

Riepilogo

A questo punto dovresti esserti fatto un'idea di come scrivere una classe di attività in background, registrare l'attività in background dall'interno dell'app e fare in modo che l'app riconosca quando l'attività in background è stata completata. Dovresti anche essere in grado di aggiornare il manifesto dell'applicazione affinché il sistema operativo consenta all'app di registrare le attività in background.

Nota Puoi scaricare l'esempio di attività in background per visualizzare questi esempi di codice, e altro ancora, nel contesto di un'app JavaScript completa e avanzata che usa attività in background.