How to use the maintenance trigger (XAML)

[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 use the MaintenanceTrigger class to run lightweight code in the background while the device is plugged in.

What you need to know

Technologies

Prerequisites

  • This example assumes that you have lightweight code you can run in the background to enhance your app while the device is plugged in. This topic focuses on the MaintenanceTrigger class, which is similar to SystemTrigger in that the app is not required to be on the lock screen to register a MaintenanceTrigger background task. More information on writing a background task class is available in Quickstart: Create and register a background task.

Instructions

Step 1: Create a maintenance trigger object

  • Create a new MaintenanceTrigger object. The second parameter, OneShot, specifies whether the maintenance task will run once or continue to run 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.

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

     

    This example code creates a trigger that runs once an hour:

    uint waitIntervalMinutes = 60;
    
    MaintenanceTrigger taskTrigger = new MaintenanceTrigger(waitIntervalMinutes, false);
    
    unsigned int waitIntervalMinutes = 60;
    
    MaintenanceTrigger ^ taskTrigger = ref new MaintenanceTrigger(waitIntervalMinutes, false);
    

Step 2: (Optional) Add a condition

  • If necessary, create a background task condition to control when the task runs. A condition prevents your 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 InternetAvailable so that maintenance runs when the Internet is available (or when it becomes available). For a list of possible background task conditions, see SystemConditionType.

    The following code adds a condition to the maintenance task builder:

    SystemCondition exampleCondition = new SystemCondition(SystemConditionType.InternetAvailable);
    
    SystemCondition ^ exampleCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);
    

Step 3: 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 maintenance task:

    string entryPoint = "Tasks.ExampleBackgroundTaskClass";
    string taskName   = "Maintenance background task example";
    
    BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition);
    
    String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass";
    String ^ taskName   = "Maintenance background task example";
    
    BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition);
    

    Note  

    For Windows Phone Store apps, if the device becomes low on memory, background tasks may be terminated without any warning and without raising the OnCanceled event. This helps to ensure the user experience of the app in the foreground. Your background task should be designed to handle this scenario., you must call RequestAccessAsync before attempting to register any background task. On Windows, this call is only required for the set of background tasks that require your app to be on the lock screen to run, but on the phone you must call this method once before registering any background task.

    To ensure that your Windows Phone Store 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 (Windows Runtime apps).

    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

Maintenance trigger events will not fire unless the device is plugged in.

Note  If the device is unplugged, all background tasks currently running that were started by the MaintenanceTrigger are canceled (cancelReason = Abort). If the background task does not cancel within 5 seconds of receiving the background task cancelled event, it will be terminated. For more info see How to handle a cancelled background task.

 

Quickstart: Create and register a background task

How to register a background task

How to respond to system events with background tasks

How to set conditions for running a background task

How to declare background tasks in the application manifest

How to debug a background task

Guidelines and checklists for background tasks