How to respond to system events with background tasks (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 create a background task that responds to system event triggers. Windows Store apps persist the user experience, even when the app is not in the foreground, by associating lightweight custom code with SystemTrigger events. This custom code runs in background tasks.
What you need to know
Technologies
Prerequisites
- This topic assumes that you have a background task class written for your app, and that this task needs to run in response to an event triggered by the system such as the internet becoming available or the user logging in. Your app does not have to be on the lock screen in order to run background tasks registered using the SystemTrigger and MaintenanceTrigger classes. This topic focuses on the SystemTrigger class. More information on writing a background task class is available in Quickstart: Create and register a background task.
Instructions
Step 1: Create a SystemTrigger object
In your app code, create a new SystemTrigger object. The first parameter, triggerType, specifies the type of system event trigger that will activate this background task. For a list of event types, see SystemTriggerType.
The second parameter, OneShot, specifies whether the background task will run once the next time the system event occurs and triggers background tasks; or, every time the system event occurs, until the task is unregistered.
The following code specifies that the background task runs whenever the Internet becomes available:
var internetTrigger = new Windows.ApplicationModel.Background.SystemTrigger(InternetAvailable, false);
Step 2: (Optional) Add a condition
If necessary, add a background task condition to control when the task will runs. A condition prevents the background task from running until the condition is met - for more information, see How to set conditions for running a background task.
In this example, the condition is set to UserPresent so that the background task only runs when the user is actively using the device (or when the user becomes available). For a list of possible background task conditions, see SystemConditionType.
The following code adds a condition to the background task:
var exampleCondition = new Windows.ApplicationModel.Background.SystemCondition(Windows.ApplicationModel.Background.SystemCondition.UserPresent);
Step 3: Register the background task
Register the background task by calling your background task registration function. For more information on registering background tasks, see How to register a background task.
The following code registers the background task:
var entryPoint = “js\\ExampleBackgroundTask.js”;
var taskName = “Internet-based background task”;
var task = RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition);
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.
Remarks
To see background task registration in action, download the background task sample.
Background tasks can run in response to SystemTrigger and MaintenanceTrigger events without being placed on the lock screen, but you still need to Declare background tasks in the application manifest. On phone, you must also call RequestAccessAsync before registering any background task type.
Lock screen-capable apps can register background tasks that respond to TimeTrigger, PushNotificationTrigger, and NetworkOperatorNotificationTrigger events, enabling them to provide real-time communication with the user even when the app is not in the foreground. For more information, see Supporting your app with background tasks.
Related topics
Quickstart: Create and register a background task
How to register a background task
How to set conditions for running a background task
How to use maintenance triggers
How to declare background tasks in the application manifest