In this article

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

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:

Add the SystemCondition object to your background task

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

taskBuilder.AddCondition(internetCondition);

taskBuilder->AddCondition(internetCondition);

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:

BackgroundTaskRegistration task = taskBuilder.Register();

BackgroundTaskRegistration ^ task = taskBuilder->Register();

Note

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

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.

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:

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.