How to use the ServicingComplete trigger (HTML)

Article
10/06/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

Learn how to use the ServicingComplete SystemTrigger to control background task registration after app updates.

What you need to know

Technologies

Windows.ApplicationModel.Background

Prerequisites

This topic applies to any app that runs one or more background tasks. More information on writing a background task class is available in Quickstart: Create and register a background task.

Instructions

Step 1: Create a ServicingComplete background task

Background task registrations persist across app updates. If an app is updated, its registrations continue to be valid and will be triggered. An app can register a background task with the ServicingComplete trigger to be notified when the app is updated, and unregister background tasks that are no longer valid.

Create a new JavaScript file for the background task.

The following sample code shows a basic starting point for a background task:

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

})();

Find the registration object for the background task that needs to be unregistered. Call Unregister to unregister the task. Note that you can force the background task to stop running (if an instance is active) by setting the cancelTask parameter to 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();

})();

Register replacement tasks as appropriate. Use a background task registration function, like the one specified in How to register a background task, to simplify the work.

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

})();

Step 2: Register the ServicingComplete background task

The ServicingComplete background task should be registered along with other background tasks, so that it can be triggered when the app is updated. The entry point for the ServicingComplete background task must remain the same in the app update.

Create a new SystemTrigger object:
- The first parameter, triggerType, should be set to servicingComplete.
- The second parameter, OneShot, should be set to false.
This example code creates a ServicingComplete trigger:
```
var background = Windows.ApplicationModel.Background;

var servicingCompleteTrigger = new background.SystemTrigger(
                        background.SystemTriggerType.servicingComplete, false);
```
Note Adding a condition to a ServicingComplete background task trigger is not recommended.
Call your background task registration function to register the task. For more information on registering background tasks, see How to register a background task.

The following code registers the ServicingComplete task:
```
var entryPoint = "js\\ServicingCompleteTask.js";
var taskName = "ServicingComplete background task";

var task = RegisterBackgroundTask(entryPoint,
                                  taskName, 
                                  servicingCompleteTrigger, 
                                  null);
```
Note In Windows Phone Store apps, you must call RequestAccessAsync once before registering any background tasks.

Step 3: Declare the background task in the package manifest

The ServicingComplete background task needs to be listed in the package manifest, just like any other background task. For more info see How to declare background tasks in the application manifest. For example:

ServicingCompleteTask declared in the app manifest