How to set conditions for running a background task (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.
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.
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);
The following code registers the InternetAvailable background task condition with the TaskBuilder:
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:
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).
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.
To add multiple conditions, your app makes multiple calls to the AddCondition method. These calls must come before task registration to be effective.
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();
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