How to respond to system events with background tasks (XAML)

[アーティクル]
10/06/2015

[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 SystemTrigger events.

What you need to know

Technologies

Windows.ApplicationModel.Background

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:
```
SystemTrigger internetTrigger = new SystemTrigger(SystemTriggerType.InternetAvailable, false);
```
```
SystemTrigger ^ internetTrigger = ref new SystemTrigger(SystemTriggerType::InternetAvailable, false);
```

Step 2:

If necessary, add a background task condition to control when your task 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:
```
SystemCondition exampleCondition = new SystemCondition(SystemConditionType.UserPresent);
```
```
SystemCondition ^ exampleCondition = ref new SystemCondition(SystemConditionType::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:
```
string entryPoint = "Tasks.ExampleBackgroundTaskClass";
string taskName   = "Internet-based background task";

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition);
```
```
String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass";
String ^ taskName   = "Internet-based background task";

BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition);
```
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.

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.

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

How to debug a background task

Guidelines and checklists for background tasks