Upravit

Sdílet prostřednictvím

Respond to system events with background tasks

  • Článek

Important APIs

Learn how to create a background task that responds to SystemTrigger events.

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 when internet availability changes or the user logging in. This topic focuses on the SystemTrigger class. More information on writing a background task class is available in Create and register an in-process background task or Create and register an out-of-process background task.

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 only once the next time the system event occurs 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);

Windows::ApplicationModel::Background::SystemTrigger internetTrigger{
    Windows::ApplicationModel::Background::SystemTriggerType::InternetAvailable, false};

SystemTrigger ^ internetTrigger = ref new SystemTrigger(SystemTriggerType::InternetAvailable, false);

Register the background task

Register the background task by calling your background task registration function. For more information on registering background tasks, see Register a background task.

The following code registers the background task for a background process that runs out-of-process. If you were calling a background task that runs in the same process as the host app, you would not set entrypoint:

string entryPoint = "Tasks.ExampleBackgroundTaskClass"; // Namespace name, '.', and the name of the class containing the background task
string taskName   = "Internet-based background task";

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition);

std::wstring entryPoint{ L"Tasks.ExampleBackgroundTaskClass" }; // don't set for in-process background tasks.
std::wstring taskName{ L"Internet-based background task" };

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{
    RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition) };

String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass"; // don't set for in-process background tasks
String ^ taskName   = "Internet-based background task";

BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, internetTrigger, exampleCondition);

Note

Universal Windows Platform apps must call RequestAccessAsync before registering any of the background trigger types.

To ensure that your Universal Windows 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.

Note

Background task registration parameters are validated at the time of registration. An error is returned if any of the registration parameters are invalid. Ensure that your app gracefully handles scenarios where background task registration fails - if instead your app depends on having a valid registration object after attempting to register a task, it may crash.  

Remarks

To see background task registration in action, download the background task sample.

Background tasks can run in response to SystemTrigger and MaintenanceTrigger events, but you still need to Declare background tasks in the application manifest. You must also call RequestAccessAsync before registering any background task type.

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 Support your app with background tasks.