How to monitor background task progress and completion (HTML)

Article
10/06/2015

[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 your app can recognize progress and completion reported by a background task. Background tasks are decoupled from the app, and they run separately, but background task progress and completion can be monitored by app code. To make this happen, the app subscribes to events from the background task(s) it has registered with the system.

What you need to know

Technologies

Windows.ApplicationModel.Background

Prerequisites

This topic assumes that you have an app that registers background tasks. 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 function that will be attached to the event handler for background task completion. This function must take a BackgroundTaskCompletedEventArgs object and no other parameters.

If you are registering a function locally, you can use the following footprint:
```
function OnCompleted(args)
{
    // TODO: Add code that deals with background task completion.
}
```
Then you can register it like so with your BackgroundTaskRegistration object (obtained using a successful call to the Register function):
```
backgroundTaskRegistration.addEventListener("completed", onCompleted);
```

You'll need to add your code that deals with background task completion.

For example, the background task sample updates the UI with the completion status saved in LocalSettings:

function OnCompleted(args)
{
    // 
    // 
    // 
    backgroundTaskName = this.name;

    // 
    // Call a method to update the UI (beyond the scope of this example).
    // 
    UpdateUI();
}

A robust app can check for exceptions thrown by the background task by calling CheckResult.

The background task sample method can be modified as follows to handle exceptions thrown by the background task:

function OnCompleted(task, args)
{
    var settings = ApplicationData.Current.LocalSettings;
    var key = task.TaskId.ToString();

    try
    {
        args.CheckResult();
        BackgroundTaskSample.SampleBackgroundTaskStatus = settings.Values[key].ToString();
    }
    catch (Exception ex)
    {
        BackgroundTaskSample.SampleBackgroundTaskStatus = "Error: " + ex.Message;
    }

    UpdateUI();
}

Step 2:

Create an event handler function to handle completed background tasks. This code needs to follow a specific footprint, which takes in an IBackgroundTaskRegistration object and a BackgroundTaskProgressEventArgs object:

Use the following footprint for the OnProgress background task event handler method:
```
function OnProgress(task, args)
{
    // TODO: Add code that deals with background task progress.
}
```
Add code to the event handler that deals with the background task completion.

For example, the background task sample updates the UI with the progress status passed in via the args parameter:
```
function OnProgress(task, args)
{
    var progress = "Progress: " + args.Progress + "%";
    BackgroundTaskSample.SampleBackgroundTaskProgress = progress;
    UpdateUI();
}
```

Step 3:

When the app registers a background task for the first time, it should register to receive progress and completion updates for it, in case the task runs while the app is still active in the foreground.

For example, the background task sample calls the following function on each background task that it registers:
```
function AttachProgressAndCompletedHandlers(IBackgroundTaskRegistration task)
{
    task.Progress += new BackgroundTaskProgressEventHandler(OnProgress);
    task.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);
}
```
When the app launches, or navigates to a new page where background task status is relevant, it should get a list of background tasks currently registered and associate them with the progress and completion event handler functions. The list of background tasks currently registered by the application is kept in the BackgroundTaskRegistration.AllTasks property.

For example, the background task sample uses the following code to attach event handlers when the SampleBackgroundTask page is navigated to:
```
function OnNavigatedTo(NavigationEventArgs e)
{
    foreach (var task in BackgroundTaskRegistration.AllTasks)
    {
        if (task.Value.Name == BackgroundTaskSample.SampleBackgroundTaskName)
        {
            AttachProgressAndCompletedHandlers(task.Value);
            BackgroundTaskSample.UpdateBackgroundTaskStatus(BackgroundTaskSample.SampleBackgroundTaskName, true);
        }
    }

    UpdateUI();
}
```