Supervisar el progreso y la finalización de tareas en segundo planoMonitor background task progress and completion

API importantesImportant APIs

Aprende cómo la aplicación puede reconocer el progreso y la finalización notificados por una tarea en segundo plano que se ejecuta fuera del proceso.Learn how your app can recognize progress and completion reported by a background task that runs out-of-process. (Para tareas en segundo plano dentro del proceso, puedes establecer variables compartidas para indicar el progreso y finalización).(For in-process background tasks, you can set shared variables to signify progress and completion.)

El código de la aplicación puede supervisar el progreso y la finalización de la tarea en segundo plano.Background task progress and completion can be monitored by app code. Para ello, la aplicación se suscribe a eventos de las tareas en segundo plano que ha registrado con el sistema.To do so, the app subscribes to events from the background task(s) it has registered with the system.

Crear un controlador de eventos para controlar las tareas en segundo plano finalizadasCreate an event handler to handle completed background tasks

Paso 1Step 1

Crea una función de controlador de eventos para controlar las tareas en segundo plano finalizadas.Create an event handler function to handle completed background tasks. Este código debe seguir una superficie específica, que toma un objeto IBackgroundTaskRegistration y un objeto BackgroundTaskCompletedEventArgs .This code needs to follow a specific footprint, which takes an IBackgroundTaskRegistration object and a BackgroundTaskCompletedEventArgs object.

Use la siguiente superficie para el método de controlador de eventos de tarea en segundo plano Alfinalizar .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.
};

Paso 2Step 2

Agrega código al controlador de eventos que se encarga de la finalización de la tarea en segundo plano.Add code to the event handler that deals with the background task completion.

Por ejemplo, la muestra de tarea en segundo plano actualiza la interfaz de usuario.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();
};

Crear una función de controlador de eventos para controlar el progreso de las tareas en segundo planoCreate an event handler function to handle background task progress

Paso 1Step 1

Crea una función de controlador de eventos para controlar las tareas en segundo plano finalizadas.Create an event handler function to handle completed background tasks. Este código necesita seguir una superficie específica, que toma un objeto IBackgroundTaskRegistration y un objeto BackgroundTaskProgressEventArgs:This code needs to follow a specific footprint, which takes in an IBackgroundTaskRegistration object and a BackgroundTaskProgressEventArgs object:

Usa la siguiente superficie para el método OnProgress del controlador de eventos de tarea en segundo plano: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.
};

Paso 2Step 2

Agrega código al controlador de eventos que se encarga de la finalización de la tarea en segundo plano.Add code to the event handler that deals with the background task completion.

Por ejemplo, la muestra de tarea en segundo plano actualiza la interfaz de usuario con el estado de progreso pasado a través del 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();
};

Registrar las funciones del controlador de eventos con tareas en segundo plano nuevas y existentesRegister the event handler functions with new and existing background tasks

Paso 1Step 1

Cuando la aplicación registra una tarea en segundo plano por primera vez, debería registrarla para recibir actualizaciones de progreso y finalización referentes a ella, en caso de que la tarea se ejecute mientras la aplicación sigue activa en primer 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 ejemplo, la muestra de tarea en segundo plano llama a la siguiente función en todas las tareas en segundo plano que 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);
}

Paso 2Step 2

Cuando la aplicación se ejecuta o navega a una página nueva en la que es relevante el estado de la tarea en segundo plano, debería obtener una lista de las tareas en segundo plano registradas actualmente y asociarlas con las funciones del controlador de eventos de progreso y finalización.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. La lista de tareas en segundo plano actualmente registradas por la aplicación se conserva en la propiedad BackgroundTaskRegistration.AllTasks.The list of background tasks currently registered by the application is kept in the BackgroundTaskRegistration.AllTasks property.

Por ejemplo, la muestra de tarea en segundo plano usa el siguiente código para adjuntar controladores de eventos cuando se navega por la página SampleBackgroundTask 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();
}