Language: HTML | XAML

How to monitor background task progress and completion (HTML)

Applies to Windows and Windows Phone

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

Prerequisites

Instructions

Step 1:

  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);
    
    
  2. 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();
    }
    
    
  3. 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:

  1. 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.
    }
    
    
  2. 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:

Register the event handler functions with new and existing background tasks.

  1. 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);
    }
    
    
  2. 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();
    }
    
    

Related topics

Quickstart: Create and register a background task
How to debug a background task
Supporting your app with background tasks
How to handle a cancelled background task
How to get a list of pending background tasks
How to declare background tasks in the application manifest
Guidelines and checklists for background tasks

 

 

Show:
© 2014 Microsoft