Share via

How to run a background task on a timer (XAML)

  • Article

[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 schedule a one-time background task, or run a periodic background task associated with your lock screen-enabled app. If the user places your app on the lock screen, your app can register a background task that runs up to every 15 minutes on Windows and every 30 minutes on Windows Phone. For example, a background task can be used to provide periodic tile or badge updates.

What you need to know

Technologies

Prerequisites

  • This example assumes that you have a background task that needs to run periodically, or at a specific time, to support your app. On Windows, a background task will only run using a TimeTrigger if you have requested that your app be placed on the lock screen with a call to RequestAccessAsync and the user accepts the prompt. On Windows Phone, you must call RequestAccessAsync, but there is no user prompt. For more information see Displaying tiles on the lock screen.
  • This topic assumes you have already created a background task class, including the Run method that is used as the background task entry point. To get started quickly building a background task, see Quickstart: Create and register a background task. For more in-depth information on conditions and triggers, see Support your app with background tasks.

Instructions

Step 1: Create a time trigger

  • Create a new TimeTrigger. The second parameter, OneShot, specifies whether the background task will run once or keep running periodically. If OneShot is set to true, the first parameter (FreshnessTime) specifies the number of minutes to wait before scheduling the background task. If OneShot is set to false, FreshnessTime specifies the frequency by which the background task will run.

    Windows has a built-in timer that runs background tasks in 15-minute intervals. Note that on Windows Phone, the interval is 30 minutes.

    • If FreshnessTime is set to 15 minutes and OneShot is true, the task will run once starting between 0 and 15 minutes from the time it is registered.

    • If FreshnessTime is set to 15 minutes and OneShot is false, the task will run every 15 minutes starting between 0 and 15 minutes from the time it is registered.

    Note  If FreshnessTime is set to less than 15 minutes, an exception is thrown when attempting to register the background task.

     

    For example, this trigger will cause a background task to run once an hour:

    TimeTrigger hourlyTrigger = new TimeTrigger(60, false);

    TimeTrigger ^ hourlyTrigger = ref new TimeTrigger(60, false);

Step 2: (Optional) Add a condition

  • If necessary, 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 How to set conditions for running a background task.

    In this example the condition is set to UserPresent so that, once triggered, the task only runs once the user is active. For a list of possible conditions, see SystemConditionType.

    SystemCondition userCondition = new SystemCondition(SystemConditionType.UserPresent);

    SystemCondition ^ userCondition = ref new SystemCondition(SystemConditionType::UserPresent)

Step 3: Request lock screen access

  • Before trying to register the TimeTrigger background task, request permission from the user to be added to the lock screen by calling RequestAccessAsync.

    On Windows, the following code presents a dialog box to the user requesting that your app be added to the lock screen. On phone, this just requests for the system to grant your app the ability to run background tasks:

    BackgroundExecutionManager.RequestAccessAsync();

    BackgroundExecutionManager::RequestAccessAsync();

    Note  An app is allowed to ask for lock screen access only once. The user can choose only one of the two options, so their preference will have been stated. Further calls to RequestAccessAsync will be ignored.

     

Step 4: 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   = “Example hourly background task”;

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, hourlyTrigger, userCondition);

    String ^ entryPoint = “Tasks.ExampleBackgroundTaskClass”;
String ^ taskName   = “Example hourly background task”;

BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, hourlyTrigger, userCondition);

    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

Note  On Windows, background tasks will only register with a time trigger if the user has added your app to the lock screen (or provided permission when your app requests access) - see Displaying tiles on the lock screen. Background tasks can be associated with triggers that don't require the app to be on the lock screen. For guidance on these types of background task triggers, see Supporting your app with background tasks.

 

Quickstart: Create and register a background task

How to register a background task

How to declare background tasks in the application manifest

How to debug a background task

Guidelines and checklists for background tasks