How to run a background task on a timer (Windows Store apps using C#/VB/C++ and XAML)
Learn how to schedule a one-time background task, or run a periodic background task associated with your Windows Store app that uses the lock screen. If the user places your app on the lock screen, your app can register a background task that runs up to every 15 minutes. For example, a background task can be used to provide periodic tile or badge updates.
- This example assumes that you have a background task that needs to run periodically, or at a specific time, to support your Windows Store app. A background task will only run using a TimeTrigger if the user has placed your app on the lock screen. 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.
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 8 has a built-in timer that runs background tasks in 15-minute intervals.
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:
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.
The following code presents a dialog box to the user requesting that your app be added to the lock screen:
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.
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);
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.
Note 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.
Note 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
Build date: 11/16/2013