Monitorar o progresso e a conclusão de tarefas em segundo planoMonitor background task progress and completion

APIs importantesImportant APIs

Saiba como o aplicativo pode reconhecer o progresso e a conclusão relatados por uma tarefa em segundo plano executada em um processo à parte.Learn how your app can recognize progress and completion reported by a background task that runs out-of-process. (Para tarefas em segundo plano no processo, você pode definir variáveis compartilhadas para indicar o andamento e a conclusão.)(For in-process background tasks, you can set shared variables to signify progress and completion.)

O progresso e a conclusão da tarefa em segundo plano podem ser monitorados pelo código do aplicativo.Background task progress and completion can be monitored by app code. Para fazer isso, o aplicativo assina eventos das tarefas em segundo plano que ele registrou no sistema.To do so, the app subscribes to events from the background task(s) it has registered with the system.

Criar um manipulador de eventos para gerenciar as tarefas em segundo plano concluídasCreate an event handler to handle completed background tasks

Etapa 1Step 1

Crie uma função de manipulador de eventos para gerenciar as tarefas em segundo plano concluídas.Create an event handler function to handle completed background tasks. Esse código precisa seguir uma superfície específica, que usa um objeto IBackgroundTaskRegistration e um objeto BackgroundTaskCompletedEventArgs .This code needs to follow a specific footprint, which takes an IBackgroundTaskRegistration object and a BackgroundTaskCompletedEventArgs object.

Use a seguinte superfície para o método de manipulador de eventos de tarefa em segundo plano OnCompleted .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.
}
auto completed{ [this](
        Windows::ApplicationModel::Background::BackgroundTaskRegistration const& /* sender */,
        Windows::ApplicationModel::Background::BackgroundTaskCompletedEventArgs const& /* 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.
};

Etapa 2Step 2

Adicione código ao manipulador de eventos que gerencia a conclusão da tarefa em segundo plano.Add code to the event handler that deals with the background task completion.

Por exemplo, o exemplo de tarefa em segundo plano atualiza a interface do usuário.For example, the background task sample updates the UI.

private void OnCompleted(IBackgroundTaskRegistration task, BackgroundTaskCompletedEventArgs args)
{
    UpdateUI();
}
auto completed{ [this](
        Windows::ApplicationModel::Background::BackgroundTaskRegistration const& /* sender */,
        Windows::ApplicationModel::Background::BackgroundTaskCompletedEventArgs const& /* args */)
{
    UpdateUI();
} };
auto completed = [this](BackgroundTaskRegistration^ task, BackgroundTaskCompletedEventArgs^ args)
{    
    UpdateUI();
};

Criar uma função de manipulador de eventos para gerenciar o andamento das tarefas em segundo planoCreate an event handler function to handle background task progress

Etapa 1Step 1

Crie uma função de manipulador de eventos para gerenciar as tarefas em segundo plano concluídas.Create an event handler function to handle completed background tasks. Este código deve seguir um volume de memória específico, que tenha um objeto IBackgroundTaskRegistration e um objeto BackgroundTaskProgressEventArgs:This code needs to follow a specific footprint, which takes in an IBackgroundTaskRegistration object and a BackgroundTaskProgressEventArgs object:

Use o seguinte volume de memória para o método manipulador de eventos de tarefa em segundo plano OnProgress: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.
}
auto progress{ [this](
    Windows::ApplicationModel::Background::BackgroundTaskRegistration const& /* sender */,
    Windows::ApplicationModel::Background::BackgroundTaskProgressEventArgs const& /* 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.
};

Etapa 2Step 2

Adicione código ao manipulador de eventos que gerencia a conclusão da tarefa em segundo plano.Add code to the event handler that deals with the background task completion.

Por exemplo, o exemplo de tarefa em segundo plano atualiza a interface do usuário com o status de progresso informado pelo parâmetro args: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();
}
auto progress{ [this](
    Windows::ApplicationModel::Background::BackgroundTaskRegistration const& /* sender */,
    Windows::ApplicationModel::Background::BackgroundTaskProgressEventArgs const& args)
{
    winrt::hstring progress{ L"Progress: " + winrt::to_hstring(args.Progress()) + L"%" };
    BackgroundTaskSample::SampleBackgroundTaskProgress = progress;
    UpdateUI();
} };
auto progress = [this](BackgroundTaskRegistration^ task, BackgroundTaskProgressEventArgs^ args)
{
    auto progress = "Progress: " + args->Progress + "%";
    BackgroundTaskSample::SampleBackgroundTaskProgress = progress;
    UpdateUI();
};

Registre as funções do manipulador de eventos com as tarefas em segundo plano novas e existentesRegister the event handler functions with new and existing background tasks

Etapa 1Step 1

Quando o aplicativo registra uma tarefa em segundo plano pela primeira vez, ele deve se registrar para receber atualizações de progresso e conclusão dessa tarefa, caso ela seja executada enquanto o aplicativo ainda estiver ativo no primeiro plano.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.

Por exemplo, o exemplo de tarefa em segundo plano chama a seguinte função em cada tarefa em segundo plano que ela registra: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);
}
void SampleBackgroundTask::AttachProgressAndCompletedHandlers(Windows::ApplicationModel::Background::IBackgroundTaskRegistration const& task)
{
    auto progress{ [this](
        Windows::ApplicationModel::Background::BackgroundTaskRegistration const& /* sender */,
        Windows::ApplicationModel::Background::BackgroundTaskProgressEventArgs const& args)
    {
        winrt::hstring progress{ L"Progress: " + winrt::to_hstring(args.Progress()) + L"%" };
        BackgroundTaskSample::SampleBackgroundTaskProgress = progress;
        UpdateUI();
    } };

    task.Progress(progress);

    auto completed{ [this](
        Windows::ApplicationModel::Background::BackgroundTaskRegistration const& /* sender */,
        Windows::ApplicationModel::Background::BackgroundTaskCompletedEventArgs const& /* args */)
    {
        UpdateUI();
    } };

    task.Completed(completed);
}
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);
}

Etapa 2Step 2

Quando o aplicativo é iniciado ou navega para uma nova página onde o status da tarefa em segundo plano é irrelevante, ele deve obter uma lista das tarefas em segundo plano atualmente registradas e associá-las às funções do manipulador de eventos de progresso e conclusão.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. A lista das tarefas em segundo plano atualmente registradas pelo aplicativo é mantida na propriedade BackgroundTaskRegistration.AllTasks.The list of background tasks currently registered by the application is kept in the BackgroundTaskRegistration.AllTasks property.

Por exemplo, o exemplo de tarefa em segundo plano usa o seguinte código para anexar manipuladores de eventos quando a página SampleBackgroundTask é navegada para: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();
}
void SampleBackgroundTask::OnNavigatedTo(Windows::UI::Xaml::Navigation::NavigationEventArgs const& /* e */)
{
    // A pointer back to the main page. This is needed if you want to call methods in MainPage such
    // as NotifyUser().
    m_rootPage = MainPage::Current;

    // Attach progress and completed handlers to any existing tasks.
    auto allTasks{ Windows::ApplicationModel::Background::BackgroundTaskRegistration::AllTasks() };

    for (auto const& task : allTasks)
    {
        if (task.Value().Name() == SampleBackgroundTaskName)
        {
            AttachProgressAndCompletedHandlers(task.Value());
            break;
        }
    }

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