Language: HTML | XAML

How to monitor background task progress and completion (XAML)

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 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 BackgroundTaskCompletedEventArgs object.

    Use the following footprint for the OnCompleted background task event handler method:

    
    private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
    {
        // TODO: Add code that deals with background task completion.
    }
    
    
  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 completion status saved in LocalSettings:

    
    private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
    {
        var settings = ApplicationData.Current.LocalSettings;
        var key = task.TaskId.ToString();
        BackgroundTaskSample.SampleBackgroundTaskStatus = settings.Values[key].ToString();
    
        UpdateUI();
    }
    
    
  3. A robust app can check for exceptions thrown by the background task by calling CheckResult.

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

    
    private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs 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:

    
    private void OnProgress(IBackgroundTaskRegistration task, BackgroundTaskProgressEventArgs 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:

    
    private void OnProgress(IBackgroundTaskRegistration task, BackgroundTaskProgressEventArgs 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:

    
    
    private void 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:

    
    
    protected override void 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 register a background task
How to get a list of pending background tasks
How to handle a cancelled background task
How to declare background tasks in the application manifest
How to debug a background task
Guidelines and checklists for background tasks

 

 

Show:
© 2014 Microsoft