Edit

Share via

Set conditions for running a background task

  • Article

Important APIs

Learn how to set conditions that control when your background task will run.

Sometimes, background tasks require certain conditions to be met for the background task to 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 then be queued, but it will not run until all the required conditions are satisfied.

Putting conditions on background tasks saves battery life and CPU 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 only running the background task when the timer has elapsed and the Internet is available.

It is also possible to combine multiple conditions by calling AddCondition multiple times on the same TaskBuilder. Take care not to add conflicting conditions, such as UserPresent and UserNotPresent.

Create a SystemCondition object

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. See Create and register an in-process background task or Create and register an out-of-process background task if you need to create a background task first.

This topic applies to background tasks that run out-of-process as well as those that run in the same process as the foreground app.

Before adding the condition, create a SystemCondition object to represent the condition that must be in effect for a background task to run. In the constructor, specify the condition that must be met with a SystemConditionType enumeration value.

The following code creates a SystemCondition object that specifies the InternetAvailable condition:

SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);

Windows::ApplicationModel::Background::SystemCondition internetCondition{
    Windows::ApplicationModel::Background::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 uses taskBuilder to add the InternetAvailable condition.

taskBuilder.AddCondition(internetCondition);

taskBuilder.AddCondition(internetCondition);

taskBuilder->AddCondition(internetCondition);

Register your background task

Now you can register your background task with the Register method, and the background 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();

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{ recurringTaskBuilder.Register() };

BackgroundTaskRegistration ^ task = taskBuilder->Register();

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.

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.
Windows::ApplicationModel::Background::TimeTrigger hourlyTrigger{ 60, false };

Windows::ApplicationModel::Background::BackgroundTaskBuilder recurringTaskBuilder;

recurringTaskBuilder.Name(L"Hourly background task");
recurringTaskBuilder.TaskEntryPoint(L"Tasks.ExampleBackgroundTaskClass");
recurringTaskBuilder.SetTrigger(hourlyTrigger);

// Begin adding conditions.
Windows::ApplicationModel::Background::SystemCondition userCondition{
    Windows::ApplicationModel::Background::SystemConditionType::UserPresent };
Windows::ApplicationModel::Background::SystemCondition internetCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };

recurringTaskBuilder.AddCondition(userCondition);
recurringTaskBuilder.AddCondition(internetCondition);

// Done adding conditions, now register the background task.
Windows::ApplicationModel::Background::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

Choose conditions for your background task so that it only runs when it's needed, and doesn't run when it shouldn't. See SystemConditionType for descriptions of the different background task conditions.