Edit

Share via

Trigger a background task from within your app

  • Article

Learn how to use the ApplicationTrigger to activate a background task from within your app.

For an example of how to create an Application trigger, see this example.

This topic assumes that you have a background task that you want to activate from your application. If you don't already have a background task, there is a sample background task at BackgroundActivity.cs. Or, follow the steps in Create and register an out-of-process background task to create one.

Why use an application trigger

Use an ApplicationTrigger to run code in a separate process from the foreground app. An ApplicationTrigger is appropriate if your app has work that needs to be done in the background--even if the user closes the foreground app. If background work should halt when the app is closed, or should be tied to the state of the foreground process, then Extended Execution should be used, instead.

Create an application trigger

Create a new ApplicationTrigger. You could store it in a field as is done in the snippet below. This is for convenience so that we don't have to create a new instance later when we want to signal the trigger. But you can use any ApplicationTrigger instance to signal the trigger.

C# 
// _AppTrigger is an ApplicationTrigger field defined at a scope that will keep it alive
// as long as you need to trigger the background task.
// Or, you could create a new ApplicationTrigger instance and use that when you want to
// trigger the background task.
_AppTrigger = new ApplicationTrigger();
C++/WinRT 
// _AppTrigger is an ApplicationTrigger field defined at a scope that will keep it alive
// as long as you need to trigger the background task.
// Or, you could create a new ApplicationTrigger instance and use that when you want to
// trigger the background task.
Windows::ApplicationModel::Background::ApplicationTrigger _AppTrigger;
C++ 
// _AppTrigger is an ApplicationTrigger field defined at a scope that will keep it alive
// as long as you need to trigger the background task.
// Or, you could create a new ApplicationTrigger instance and use that when you want to
// trigger the background task.
ApplicationTrigger ^ _AppTrigger = ref new ApplicationTrigger();

(Optional) Add a condition

You can create a background task condition to control when the task runs. A condition prevents the background task from running until the condition is met. For more information, see Set conditions for running a background task.

In this example the condition is set to InternetAvailable so that, once triggered, the task only runs once internet access is available. For a list of possible conditions, see SystemConditionType.

C# 
SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);
C++/WinRT 
Windows::ApplicationModel::Background::SystemCondition internetCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };
C++ 
SystemCondition ^ internetCondition = ref new SystemCondition(SystemConditionType::InternetAvailable)

For more in-depth information on conditions and types of background triggers, see Support your app with background tasks.

Call RequestAccessAsync()

Before registering the ApplicationTrigger background task, call RequestAccessAsync to determine the level of background activity the user allows because the user may have disabled background activity for your app. See Optimize background activity for more information about the ways users can control the settings for background activity.

C# 
var requestStatus = await Windows.ApplicationModel.Background.BackgroundExecutionManager.RequestAccessAsync();
if (requestStatus != BackgroundAccessStatus.AlwaysAllowed)
{
   // Depending on the value of requestStatus, provide an appropriate response
   // such as notifying the user which functionality won't work as expected
}

Register the background task

Register the background task by calling your background task registration function. For more information on registering background tasks, and to see the definition of the RegisterBackgroundTask() method in the sample code below, see Register a background task.

If you are considering using an Application Trigger to extend the lifetime of your foreground process, consider using Extended Execution instead. The Application Trigger is designed for creating a separately hosted process to do work in. The following code snippet registers an out-of-process background trigger.

C# 
string entryPoint = "Tasks.ExampleBackgroundTaskClass";
string taskName   = "Example application trigger";

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, appTrigger, internetCondition);
C++/WinRT 
std::wstring entryPoint{ L"Tasks.ExampleBackgroundTaskClass" };
std::wstring taskName{ L"Example application trigger" };

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{
    RegisterBackgroundTask(entryPoint, taskName, appTrigger, internetCondition) };
C++ 
String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass";
String ^ taskName   = "Example application trigger";

BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, appTrigger, internetCondition);

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.

Trigger the background task

Before you trigger the background task, use BackgroundTaskRegistration to verify that the background task is registered. A good time to verify that all of your background tasks are registered is during app launch.

Trigger the background task by calling ApplicationTrigger.RequestAsync. Any ApplicationTrigger instance will do.

Note that ApplicationTrigger.RequestAsync can't be called from the background task itself, or when the app is in the background running state (see App lifecycle for more information about application states). It may return DisabledByPolicy if the user has set energy or privacy policies that prevent the app from performing background activity. Also, only one AppTrigger can run at a time. If you attempt to run an AppTrigger while another is already running, the function will return CurrentlyRunning.

C# 
var result = await _AppTrigger.RequestAsync();

Manage resources for your background task

Use BackgroundExecutionManager.RequestAccessAsync to determine if the user has decided that your app’s background activity should be limited. Be aware of your battery usage and only run in the background when it is necessary to complete an action that the user wants. See Optimize background activity for more information about the ways users can control the settings for background activity.

  • Memory: Tuning your app's memory and energy use is key to ensuring that the operating system will allow your background task to run. Use the Memory Management APIs to see how much memory your background task is using. The more memory your background task uses, the harder it is for the OS to keep it running when another app is in the foreground. The user is ultimately in control of all background activity that your app can perform and has visibility on the impact your app has on battery use.
  • CPU time: Background tasks are limited by the amount of wall-clock usage time they get based on trigger type. Background tasks triggered by the Application trigger are limited to about 10 minutes.

See Support your app with background tasks for the resource constraints applied to background tasks.

Remarks

Starting with Windows 10, it is no longer necessary for the user to add your app to the lock screen in order to utilize background tasks.

A background task will only run using an ApplicationTrigger if you have called RequestAccessAsync first.