How to run a background task on a timer (Windows Store apps using JavaScript and HTML)

Learn how to schedule a one-time background task, or run a periodic background task associated with your Windows Store app. If the user places your app is on the lock screen, your app can register a background task that runs up to every 15 minutes. For example, a background task could be used to provide periodic tile or badge updates.

What you need to know

Technologies

• Windows.ApplicationModel.Background

Prerequisites

• This example assumes that you have a background task that needs to run periodically, or at a specific time, to support your Windows Store app. A background task will only run using a TimeTrigger if the user has placed your app on the lock screen. For more information see Displaying tiles on the lock screen.
• This topic assumes you have already created a background task class, including the Run method that is used as the background task entry point. To get started quickly building a background task, see Quickstart: Create and register a background task. For more in-depth information on conditions and triggers, see Support your app with background tasks.

Instructions

Step 1: Create a time trigger

Create a new TimeTrigger. The second parameter, OneShot, specifies whether the background task will run once or keep running periodically. If OneShot is set to true, the first parameter (FreshnessTime) specifies the number of minutes to wait before scheduling the background task. If OneShot is set to false, FreshnessTime specifies the frequency by which the background task will run.

Windows 8 has a built-in timer that runs background tasks in 15-minute intervals.

• If FreshnessTime is set to 15 minutes and OneShot is true, the task will run once starting between 0 and 15 minutes from the time it is registered.

• If FreshnessTime is set to 15 minutes and OneShot is false, the task will run every 15 minutes starting between 0 and 15 minutes from the time it is registered.

Note  If FreshnessTime is set to less than 15 minutes, an exception is thrown when attempting to register the background task.

For example, this trigger will cause a background task to run once an hour:

var hourlyTrigger = new Windows.ApplicationModel.Background.TimeTrigger(60, false);

Step 2: (Optional) Add a condition

If necessary, add a background task condition to control when the task runs. A condition prevents theyour background task from running until the condition is met - for more information, see How to set conditions for running a background task.

In this example the condition is set to UserPresent so that, once triggered, the task only runs when the user is active. For a list of possible conditions, see SystemConditionType.

The following code adds a condition to the background task:

var userCondition = new Windows.ApplicationModel.Background.SystemCondition(Windows.ApplicationModel.Background.SystemConditionType.UserPresent);

Step 3: Request lock screen access

Before trying to register the TimeTrigger background task, request permission from the user to be added to the lock screen by calling RequestAccessAsync.

The following code presents a dialog box to the user requesting that your app be added to the lock screen:

Windows.ApplicationModel.Background.BackgroundExecutionManager.RequestAccessAsync();

Note  An app is allowed to ask for lock screen access only once. The user can choose only one of the two options, so their preference will have been stated. Further calls to RequestAccessAsync will be ignored.

Step 4: Register the background task

Register the background task by calling your background task registration function. For more information on registering background tasks, see How to register a background task.

The following code registers the background task:

var entryPoint = “js\\ExampleBackgroundTask.js”;
var taskName = “Example hourly background task”;

var task = RegisterBackgroundTask(entryPoint, taskName, hourlyTrigger, userCondition);

Remarks

Note  Background tasks will only register with a time trigger if the user has added your app to the lock screen - see Displaying tiles on the lock screen.

Note  Background tasks can be associated with triggers that don't require the app to be on the lock screen. For guidance on these types of background task triggers, see Supporting your app with background tasks.

Related topics

Quickstart: Create and register a background task

How to register a background task

How to declare background tasks in the application manifest

How to debug a background task

Guidelines and checklists for background tasks

Build date: 10/26/2012