Language: HTML | XAML

How to use the ServicingComplete trigger (HTML)

Applies to Windows and Windows Phone

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

What you need to know

Technologies

Prerequisites

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.

  1. 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();
    
    })();
    
    
  2. 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();
    
    })();
    
    
  3. 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.

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

  2. 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);
    
    
    • Applies to Windows Phone

    Note  On Windows Phone, 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

Remarks

See How to debug a background task (Windows Store apps) for important info related to debugging app updates with background tasks.

Related topics

Quickstart: Create and register a background task
How to register a background task
How to respond to system events with background tasks
How to set conditions for running a background task
How to declare background tasks in the application manifest
How to debug a background task
Guidelines and checklists for background tasks

 

 

Show:
© 2014 Microsoft