How to set conditions for running a background task (XAML)
[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
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:
SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);
SystemCondition ^ internetCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);
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);
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.
To ensure that your Windows Phone Store 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 (Windows Runtime apps).
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.
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:
//
// Set up the background task.
//
TimeTrigger hourlyTrigger = new TimeTrigger(60, false);
var recurringTaskBuilder = new BackgroundTaskBuilder();
recurringTaskBuilder.Name = "Hourly background task";
recurringTaskBuilder.TaskEntryPoint = "Tasks.ExampleBackgroundTaskClass";
recurringTaskBuilder.SetTrigger(hourlyTrigger);
//
// Begin adding conditions.
//
SystemCondition userCondition = new SystemCondition(SystemConditionType.UserPresent);
SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);
recurringTaskBuilder.AddCondition(userCondition);
recurringTaskBuilder.AddCondition(internetCondition);
//
// Done adding conditions, now register the background task.
//
BackgroundTaskRegistration task = recurringTaskBuilder.Register();
//
// Set up the background task.
//
TimeTrigger ^ hourlyTrigger = ref new TimeTrigger(60, false);
auto recurringTaskBuilder = ref new BackgroundTaskBuilder();
recurringTaskBuilder->Name = "Hourly background task";
recurringTaskBuilder->TaskEntryPoint = "Tasks.ExampleBackgroundTaskClass";
recurringTaskBuilder->SetTrigger(hourlyTrigger);
//
// Begin adding conditions.
//
SystemCondition ^ userCondition = ref new SystemCondition(SystemConditionType::UserPresent);
SystemCondition ^ internetCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);
recurringTaskBuilder->AddCondition(userCondition);
recurringTaskBuilder->AddCondition(internetCondition);
//
// Done adding conditions, now register the background task.
//
BackgroundTaskRegistration ^ 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