author	title	description	ms.assetid	ms.author	ms.date	ms.topic	ms.prod	ms.technology	keywords	ms.localizationpriority
TylerMSFT	Monitor background task progress and completion	Learn how your app can recognize progress and completion reported by a background task.	17544FD7-A336-4254-97DC-2BF8994FF9B2	twhitney	02/08/2017	article	windows	uwp	windows 10, uwp	medium

Monitor background task progress and completion

Important APIs

Learn how your app can recognize progress and completion reported by a background task that runs out-of-process. (For in-process background tasks, you can set shared variables to signify progress and completion.)

Background task progress and completion can be monitored by app code. To do so, the app subscribes to events from the background task(s) it has registered with the system.

This topic assumes that you have an app that registers background tasks. To get started quickly building a background task, see Create and register an in-process background task or Create and register an out-of-process background task. For more in-depth information on conditions and triggers, see Support your app with background tasks.

Create an event handler to handle completed background tasks

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:

[!div class="tabbedCodeSnippets"]

 private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
 {
     // TODO: Add code that deals with background task completion.
 }

 auto completed = [this](BackgroundTaskRegistration^ task, BackgroundTaskCompletedEventArgs^ args)
 {
     // TODO: Add code that deals with background task completion.
 };

Add code to the event handler that deals with the background task completion.

For example, the background task sample updates the UI.

[!div class="tabbedCodeSnippets"]

    private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
    {
        UpdateUI();
    }

    auto completed = [this](BackgroundTaskRegistration^ task, BackgroundTaskCompletedEventArgs^ args)
    {    
        UpdateUI();
    };

Create an event handler function to handle background task progress

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:

[!div class="tabbedCodeSnippets"]

    private void OnProgress(IBackgroundTaskRegistration task, BackgroundTaskProgressEventArgs args)
    {
        // TODO: Add code that deals with background task progress.
    }

    auto progress = [this](BackgroundTaskRegistration^ task, BackgroundTaskProgressEventArgs^ 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:

[!div class="tabbedCodeSnippets"]

    private void OnProgress(IBackgroundTaskRegistration task, BackgroundTaskProgressEventArgs args)
    {
        var progress = "Progress: " + args.Progress + "%";
        BackgroundTaskSample.SampleBackgroundTaskProgress = progress;

        UpdateUI();
    }

    auto progress = [this](BackgroundTaskRegistration^ task, BackgroundTaskProgressEventArgs^ args)
    {
        auto progress = "Progress: " + args->Progress + "%";
        BackgroundTaskSample::SampleBackgroundTaskProgress = progress;

        UpdateUI();
    };

Register the event handler functions with new and existing background tasks

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:

[!div class="tabbedCodeSnippets"]

    private void AttachProgressAndCompletedHandlers(IBackgroundTaskRegistration task)
    {
        task.Progress += new BackgroundTaskProgressEventHandler(OnProgress);
        task.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);
    }

    void SampleBackgroundTask::AttachProgressAndCompletedHandlers(IBackgroundTaskRegistration^ task)
    {
        auto progress = [this](BackgroundTaskRegistration^ task, BackgroundTaskProgressEventArgs^ args)
        {
            auto progress = "Progress: " + args->Progress + "%";
            BackgroundTaskSample::SampleBackgroundTaskProgress = progress;
            UpdateUI();
        };

        task->Progress += ref new BackgroundTaskProgressEventHandler(progress);
        

        auto completed = [this](BackgroundTaskRegistration^ task, BackgroundTaskCompletedEventArgs^ args)
        {
            UpdateUI();
        };

        task->Completed += ref new BackgroundTaskCompletedEventHandler(completed);
    }

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:

[!div class="tabbedCodeSnippets"]

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

    void SampleBackgroundTask::OnNavigatedTo(NavigationEventArgs^ e)
    {
        // A pointer back to the main page.  This is needed if you want to call methods in MainPage such
        // as NotifyUser()
        rootPage = MainPage::Current;

        //
        // Attach progress and completed handlers to any existing tasks.
        //
        auto iter = BackgroundTaskRegistration::AllTasks->First();
        auto hascur = iter->HasCurrent;
        while (hascur)
        {
            auto cur = iter->Current->Value;

            if (cur->Name == SampleBackgroundTaskName)
            {
                AttachProgressAndCompletedHandlers(cur);
                break;
            }

            hascur = iter->MoveNext();
        }

        UpdateUI();
    }

Related topics