How to set conditions for running a background task (Windows Store apps using JavaScript and HTML)

Learn how to set conditions for running your background task, that help it run only when appropriate. Sometimes, background tasks require certain conditions to be met, in addition to the event that triggers the task, so that the background task can succeed. You can specify one or more of the conditions specified by SystemConditionType when registering your background task. The condition will be checked after the trigger has been fired; the background task will be queued, but it will not run until all the required conditions are satisfied.

Putting conditions on background tasks saves battery life and CPU runtime by preventing tasks from running unnecessarily. For example, if your background task runs on a timer and requires Internet connectivity, add the InternetAvailable condition to the TaskBuilder before registering the task. This will help prevent the task from using system resources and battery life unnecessarily by letting it run when the timer has elapsed and the Internet is available.

What you need to know

Technologies

• Windows.ApplicationModel.Background

Prerequisites

• This topic assumes that you have a background task already associated with your app, and that your app already includes code that creates a BackgroundTaskBuilder object named taskBuilder.

Instructions

Step 1: Create a SystemCondition object

Before adding the condition, create a SystemCondition object representing the condition that must be in effect for a background task to run. In the constructor, specify the condition that must be met by providing a SystemConditionType enumeration value.

The following code creates a SystemCondition object specifying Internet availability as the conditional requirement:

var internetCondition = new Windows.ApplicationModel.Background.SystemCondition(Windows.ApplicationModel.Background.SystemConditionType.InternetAvailable);

Step 2: Add the SystemCondition object to your background task

To add the condition, call the AddCondition method on the BackgroundTaskBuilder object, and pass it the SystemCondition object.

The following code registers the InternetAvailable background task condition with the TaskBuilder:

taskBuilder.AddCondition(internetCondition);

Step 3: Register your background task

Now you can register your background task with the Register method, and the task will not start until the specified condition is met.

The following code registers the task and stores the resulting BackgroundTaskRegistration object:

var task = taskBuilder.Register();

Step 4: Place multiple conditions on your background task

To add multiple conditions, your app makes multiple calls to the AddCondition method. These calls must come before task registration to be effective.

Note  Take care not to add conflicting conditions to a background task.

The following snippet shows multiple conditions in the context of creating and registering a background task:

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

var recurringTaskBuilder = new Windows.ApplicationModel.Background.BackgroundTaskBuilder();

recurringTaskBuilder.Name = "Hourly background task for YourApp";
recurringTaskBuilder.TaskEntryPoint = "js\\ExampleBackgroundTask.js";
recurringTaskBuilder.SetTrigger(hourlytrigger);

//
// Begin adding conditions.
//
var userCondition = new Windows.ApplicationModel.Background.SystemCondition(Windows.ApplicationModel.Background.SystemConditionType.UserPresent);
var internetCondition = new Windows.ApplicationModel.Background.SystemCondition(Windows.ApplicationModel.Background.SystemConditionType.InternetAvailable);

taskBuilder.AddCondition(userCondition);
taskBuilder.AddCondition(internetCondition);

//
// Done adding conditions. Now we register the background task.
//
var task = recurringTaskBuilder.Register();

Remarks

Note  Pick the right conditions for your background task so that it only runs when it's needed, and doesn't run when it won't work. See SystemConditionType for descriptions of the different background task conditions.

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 use maintenance triggers

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