How to set conditions for running a background task (HTML)

[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 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

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

Note  

In Windows Phone Store apps, you must call RequestAccessAsync before attempting to register any background task. On Windows, this call is only required for the set of background tasks that require your app to be on the lock screen to run, but on the phone you must call this method once before registering any background task.

To ensure that your Windows Phone app continues to run properly after you release an update, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. For more information, see Guidelines for background tasks (HTML).

Note  

Starting in Windows 8.1, background task registration parameters are validated at the time of registration. An error is returned if any of the registration parameters are invalid. Your app must be able to handle scenarios where background task registration fails - for example, use a conditional statement to check for registration errors and then retry failed registration using different parameter values.

 

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.

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