UniversalApp - BackgroundTask

Create the Background Task class

You can run code in the background by writing classes that implement the IBackgroundTask interface. This code will run when a specific event is triggered by using, for example, SystemTrigger or MaintenanceTrigger.

The following steps show you how to write a new class that implements the IBackgroundTask interface. Before getting started, create a new project in your solution for background tasks. Add a new empty class for your background task and import the Windows.ApplicationModel.Background namespace.

1. Create a new project for background tasks and add it to your solution. To do this, right-click on your solution and select Add->New Project. Then select the Windows Runtime Component project type, name the project, and click OK.
2. Reference the background tasks project from your Windows Store app or Windows Phone app project.
   For a C# app, in your app project, right click on References and select Add New Reference. Under Solution, select Projects and then select the name of your background task project and click Ok.
3. Create a new class that implements the IBackgroundTask interface. The Run method is a required entry point that will be called when the specified event is triggered; this method is required in every background task.
   Note  The background task class itself - and all other classes in the background task project - need to be public classes that are sealed.
   The following sample code shows a very basic starting point for a background task class:
   C#
   //
   // ExampleBackgroundTask.cs
   //
   
   using Windows.ApplicationModel.Background;
   
   namespace Tasks
   {
       public sealed class ExampleBackgroundTask : IBackgroundTask
       {
           public void Run(IBackgroundTaskInstance taskInstance)
           {
              
           }       
       }
   }
   
4. If you run any asynchronous code in your background task, then your background task needs to use a deferral. If you don't use a deferral, then the background task process can terminate unexpectedly if the Run method completes before your asynchronous method call has completed.
   Request the deferral in the Run method before calling the asynchronous method. Save the deferral to a global variable so it can be accessed from the asynchronous method. Declare the deferral complete after the asynchronous code completes.
   The following sample code gets the deferral, saves it, and releases it when the asynchronous code is complete:
   C#
   
   
   public async void Run(IBackgroundTaskInstance taskInstance)
   {
       BackgroundTaskDeferral _deferral = taskInstance.GetDeferral();
      
       //
       // TODO: Insert code to start one or more asynchronous methods using the
       //       await keyword, for example:
       //
       // await ExampleMethodAsync();
       //
      
       _deferral.Complete();
   }
   
   Note  In C#, your background task's asynchronous methods can be called using the async/await keywords. In C++, a similar result can be achieved by using a task chain.
   For more information on asynchronous patterns, see Asynchronous programming. For additional examples of how to use deferrals to keep a background task from stopping early, see the background task sample.

The following steps are completed in one of your app classes (for example, MainPage.xaml.cs).

Note  You can also create a function dedicated to registering background tasks - see How to register a background task. In that case, instead of using the next 3 steps, you can simply construct the trigger and provide it to the registration function along with the task name, task entry point, and (optionally) a condition.

Register the background task to run

1. Find out if the background task is already registered by iterating through the BackgroundTaskRegistration.AllTasks property. This step is important; if your app doesn't check for existing background task registrations, it could easily register the task multiple times, causing issues with performance and maxing out the task's available CPU time before work can complete.
   The following example iterates on the AllTasks property and sets a flag variable to true if the task is already registered:
   C#
   
   var taskRegistered = false;
   var exampleTaskName = "ExampleBackgroundTask";
   
   foreach (var task in Background.BackgroundTaskRegistration.AllTasks)
   {
       if (task.Value.Name == exampleTaskName)
       {
           taskRegistered = true;
           break;
       }
   }
2. If the background task is not already registered, use BackgroundTaskBuilder to create an instance of your background task. The task entry point should be the name of your background task class prefixed by the namespace.
   The background task trigger controls when the background task will run. For a list of possible triggers, see SystemTrigger.
   For example, this code creates a new background task and sets it to run when the TimeZoneChanged trigger is fired:
   C#
   
   
   var builder = new BackgroundTaskBuilder();
   
   builder.Name = exampleTaskName;
   builder.TaskEntryPoint = "Tasks.ExampleBackgroundTask";
   builder.SetTrigger(new SystemTrigger(SystemTriggerType.TimeZoneChange, false));
3. You can add a condition to control when your task will run after the trigger event occurs (optional). For example, if you don't want the task to run until the user is present, use the condition UserPresent. For a list of possible conditions, see SystemConditionType.
   The following sample code assigns a condition requiring the user to be present:
   C#
   
   builder.AddCondition(new SystemCondition(SystemConditionType.UserPresent));
4. Register the background task by calling the Register method on the BackgroundTaskBuilder object. Store the BackgroundTaskRegistration result so it can be used in the next step.
   The following code registers the background task and stores the result:
   C#
   
   BackgroundTaskRegistration task = builder.Register();

On Windows Phone, 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 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.

Handle background task completion using event handlers

You should register a method with the BackgroundTaskCompletedEventHandler, so that your app can get results from the background task. When the app is launched or resumed, the OnCompleted method will be called if the background task has completed since the last time the app was in the foreground. (The OnCompleted method will be called immediately if the background task completes while your app is currently in the foreground.)

1. Write an OnCompleted method to handle the completion of background tasks. For example, the background task result might cause a UI update. The method footprint shown here is required for the OnCompleted event handler method, even though this example does not use the args parameter.
   The following sample code recognizes background task completion and calls an example UI update method that takes a message string.
   C#
   
   
   private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
   {
       var settings = ApplicationData.Current.LocalSettings;
       var key = task.TaskId.ToString();
       var message = settings.Values[key].ToString();
       UpdateUIExampleMethod(message);
   }
   
   Note  UI updates should be performed asynchronously, to avoid holding up the UI thread. For an example, see the UpdateUI method in the background task sample.
2. Go back to where you registered the background task. After that line of code, add a new BackgroundTaskCompletedEventHandler object. Provide your OnCompleted method as the parameter for the BackgroundTaskCompletedEventHandler constructor.
   The following sample code adds a BackgroundTaskCompletedEventHandler to the BackgroundTaskRegistration:
   C#
   
   task.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);

Declare that your app uses background tasks in the app manifest

Before your app can run background tasks, you must declare each background task in the app manifest.

• Open the app manifest (the file named "package.appmanifest") and go to the Extensions element. Add an Extension element, with category set to "windows.backgroundTasks", for each background task class used in your app.
  You must list each type of trigger used with your background task. If your app attempts to register a background task with a trigger that isn't listed in the manifest, the registration will fail.
  The following Extensions sample element registers the background task created in this topic:
  XML
  Copy
  
  
  <Extensions>
    <Extension Category="windows.backgroundTasks" EntryPoint="Tasks.ExampleBackgroundTask">
      <BackgroundTasks>
        <Task Type="systemEvent" />
      </BackgroundTasks>
    </Extension>
  </Extensions>

Summary

You should now understand the basics of how to write a background task class, how to register the background task from within your app, and how to make your app recognize when the background task is complete. You should also understand how to update the application manifest so that Windows 8 will let your app register the background task.

Note  Download the background task sample to see similar code examples in the context of a complete and robust Windows Store app that uses background tasks.

See the following related topics for API reference, background task conceptual guidance, and more detailed instructions for writing apps that use background tasks.

From <http://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh977055.aspx>

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

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

• Windows.ApplicationModel.Background

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:
  C#
  C++
  Copy
  
  TimeTrigger hourlyTrigger = 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.
  C#
  C++
  Copy
  
  SystemCondition userCondition = 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:
  C#
  C++
  Copy
  
  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:
  C#
  C++
  Copy
  
  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.

From <http://msdn.microsoft.com/en-us/library/windows/apps/xaml/hh977059.aspx>