Краткое руководство: создание и регистрация фоновой задачи (HTML)

Статья
12/12/2015

[ Эта статья адресована разработчикам приложений среды выполнения Windows для Windows 8.x и Windows Phone 8.x. При разработке приложений для Windows 10 см. раздел последняя документация]

В этом разделе описаны способы создания и регистрации рабочего процесса фоновой задачи для приложения.

Необходимые условия

Выберите приложение, которому вы хотите предоставить фоновую задачу.

Создание класса фоновых задач

Создайте отдельный метод с кодом, который будет выполняться в фоновом режиме. Этот код будет запускаться при активации определенного события. В разделах SystemTrigger и MaintenanceTrigger приведен список типов триггеров, которые могут быть использованы любым приложением.

Далее будет показано, как написать рабочий процесс фоновой задачи, использующий Windows.UI.WebUI.WebUIBackgroundTaskInstance. Перед началом работы создайте пустой файл JavaScript в среде Microsoft Visual Studio.

Создайте новый файл JavaScript в вашем проекте. Функции и код в этом файле будут выполняться в фоновом режиме.

Следующий структурный код поможет вам приступить к работе:


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

})();

Фоновая задача должна понимать, когда ее запрашивают об остановке работы. Сначала добавьте прослушиватель событий для события canceled и добавьте переменную с именем canceled для передачи сигнала в фоновую задачу.

В примере фоновой задачи проверяется появление события canceled с помощью функций onCanceled:

    var cancel = false;

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

Затем измените код так, чтобы он прекращал работу и закрывался, если canceled получает значение true.

В примере фоновой задачи создается задача с именем 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();
    }

})();

Убедитесь, что ваша фоновая задача вызывает встроенный метод close() каждый раз, когда она завершает работу или отменяется. Если фоновая задача не закрывается самостоятельно, процесс фоновой задачи может продолжать существование, потребляя память и энергию батареи даже после окончания работы фоновой задачи.

Вызывайте функцию close() каждый раз, когда фоновая задача JavaScript завершает работу или отменяется:
```
close();
```

Следующие действия включают добавление кода в ваше существующее приложение (например, "default.js").

Примечание Вы также можете создать функцию для регистрации фоновых задач — см. раздел Регистрация фоновой задачи. В этом случае вместо выполнения следующих трех шагов вы можете просто создать триггер и назначить его функции регистрации, указав имя задачи, точку входа задачи и (не обязательно) условие.

Регистрация фоновой задачи

Чтобы узнать, зарегистрирована ли уже фоновая задача, выполните итерацию по свойству BackgroundTaskRegistration.allTasks. Это важный шаг: если приложение не проверяет, зарегистрирована ли уже фоновая задача, оно может выполнить регистрацию несколько раз, вызывая проблемы производительности и полное использование доступного задаче времени ЦП до завершения работы.

В следующем примере выполняется итерация по свойству allTasks, и для переменной-флага устанавливается значение "true", если задача уже зарегистрирована:
```
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();
}
```
Если фоновая задача еще не зарегистрирована, зарегистрируйте ее, вызвав функцию register и передав ей в качестве аргументов имя файла фоновой задачи и SystemTrigger.

Триггер фоновой задачи определяет, когда должна быть запущена фоновая задача. Список возможных системных триггеров см. в 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();
}
```
Вы можете добавить условие, чтобы контролировать, в какой момент времени после возникновения события триггера запустится ваша задача (не обязательно). Например, если вы не хотите, чтобы задача запускалась в отсутствие пользователя, используйте условие UserPresent. Список возможных условий см. в разделе SystemConditionType.

Примечание

Начиная с Windows 8.1 параметры регистрации фоновых задач проверяются во время регистрации. Если какие-либо из параметров регистрации недопустимы, возвращается ошибка. Приложение должно быть способно обрабатывать сценарии, где не удается зарегистрировать фоновые задачи (например, использовать условный оператор для проверки наличия регистрационных ошибок, а затем повторять попытку неудавшейся регистрации с использованием других значений параметров).
```
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();
}
```
Примечание

Для универсальных приложений Windows Phone необходимо вызывать метод RequestAccessAsync перед регистрацией любой фоновой задачи. В Windows такой вызов требуется только для набора фоновых задач, для выполнения которых приложение должно находиться на экране блокировки, однако в Windows Phone вы должны один раз вызывать этот метод перед регистрацией любой фоновой задачи.

Чтобы приложение Windows Phone продолжало правильно работать после выпуска обновления, необходимо вызвать RemoveAccess, а затем RequestAccessAsync при запуске приложения после обновления. Дополнительная информация: Руководство по фоновым задачам (HTML).

Обработка завершения фоновых задач

В вашем приложении может наблюдаться выполнение и завершение фоновых задач путем регистрации для прослушивателя событий Completed при каждом вызове приложения.

Создайте функцию, которую приложение сможет использовать для распознавания завершения фоновых рабочих потоков.

Образец фоновой задачи добавляет функцию, называемую 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");
        }
    };
}

Подпишитесь на прослушиватель событий Completed с помощью этой функции.

Образец фоновой задачи добавляет функцию onCompleted к событию Completed:
```
task.addEventListener("completed", new BackgroundTaskSample.completeHandler(task).onCompleted);
```

Объявление использования приложением фоновых задач в манифесте приложения

Перед тем как ваше приложение сможет регистрировать фоновые задачи, вам необходимо объявить каждую такую задачу (и используемые ею триггеры) в манифесте приложения.

Откройте манифест приложения и перейдите к элементу Extensions. Добавьте элемент Extension, указав для него категорию "windows.backgroundTasks", для каждого класса фоновой задачи, используемого в вашем приложении. Необходимо перечислить каждый тип триггеров, которые использует фоновая задача. В противном случае ваше приложение не сможет зарегистрировать фоновые задачи с необъявленными типами триггеров.

Образец фоновой задачи регистрирует три рабочих потока фоновой задачи:
```
<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>
```

Сводка

Теперь вы понимаете, как создавать класс фоновой задачи, как регистрировать фоновую задачу из приложения и как заставить приложение распознавать завершение фоновой задачи. Вы также знаете, как обновить манифест приложения, чтобы ОС позволила приложению регистрировать фоновые задачи.

Примечание Скачайте образец фоновой задачи, чтобы ознакомиться с примерами кода (и не только) в контексте полного и надежного приложения JavaScript, которое использует фоновые задачи.