Como monitorar o progresso e a conclusão de tarefas em segundo plano (HTML)

Artigo
12/12/2015

[ Este artigo destina-se aos desenvolvedores do Windows 8.x e do Windows Phone 8.x que escrevem aplicativos do Windows Runtime. Se você estiver desenvolvendo para o Windows 10, consulte documentação mais recente]

Saiba como o aplicativo pode reconhecer o progresso e a conclusão relatados por uma tarefa em segundo plano. As tarefas em segundo plano são separadas do aplicativo, e são executadas separadamente, mas o progresso e a conclusão dessas tarefas podem ser monitorados por um código do aplicativo. Para fazer isso, o aplicativo assina eventos das tarefas em segundo plano que ele registrou no sistema.

O que você precisa saber

Tecnologias

Windows.ApplicationModel.Background

Pré-requisitos

Este tópico considera que você tem um aplicativo que registra tarefas em segundo plano. Para começar a criar rapidamente uma tarefa em segundo plano, veja Início rápido: criar e registrar uma tarefa em segundo plano. Para saber mais sobre condições e disparadores, veja Oferecendo suporte a tarefas em segundo plano em seu aplicativo.

Instruções

Etapa 1:

Crie uma função que será anexado ao manipulador de eventos para conclusão da tarefa em segundo plano. Esta função deve tomar um objeto BackgroundTaskCompletedEventArgs e nenhum outro parâmetro.

Se estiver registrando uma função localmente, você pode usar o seguinte volume de memória:
```
function OnCompleted(args)
{
    // TODO: Add code that deals with background task completion.
}
```
Em seguida, você pode registrá-la como se faz com um objeto BackgroundTaskRegistration (obtido com uma chamada bem-sucedida para a função Register):
```
backgroundTaskRegistration.addEventListener("completed", onCompleted);
```
Você precisará adicionar seu código que lida com a conclusão de tarefas em segundo plano.

Por exemplo, o exemplo de tarefa em segundo plano atualiza a interface do usuário com o status de conclusão salvo em LocalSettings:
```
function OnCompleted(args)
{
    // 
    // 
    // 
    backgroundTaskName = this.name;

    // 
    // Call a method to update the UI (beyond the scope of this example).
    // 
    UpdateUI();
}
```

Um aplicativo robusto pode verificar exceções lançadas pela tarefa em segundo plano chamando CheckResult.

O método do exemplo de tarefa em segundo plano pode ser modificado como a seguir para manipular as exceções lançadas pela tarefa em segundo plano:

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

Etapa 2:

Crie uma função de manipulador de eventos para gerenciar as tarefas em segundo plano concluídas. Este código deve seguir um volume de memória específico, que tenha um objeto IBackgroundTaskRegistration e um objeto BackgroundTaskProgressEventArgs:

Use o seguinte volume de memória para o método manipulador de eventos de tarefa em segundo plano OnProgress:
```
function OnProgress(task, args)
{
    // TODO: Add code that deals with background task progress.
}
```
Adicione código ao manipulador de eventos que gerencia a conclusão da tarefa em segundo plano.

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:
```
function OnProgress(task, args)
{
    var progress = "Progress: " + args.Progress + "%";
    BackgroundTaskSample.SampleBackgroundTaskProgress = progress;
    UpdateUI();
}
```

Etapa 3:

Registre as funções do manipulador de eventos com as tarefas em segundo plano novas e existentes.

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.

Por exemplo, o exemplo de tarefa em segundo plano chama a seguinte função em cada tarefa em segundo plano que ela registra:
```
function AttachProgressAndCompletedHandlers(IBackgroundTaskRegistration task)
{
    task.Progress += new BackgroundTaskProgressEventHandler(OnProgress);
    task.Completed += new BackgroundTaskCompletedEventHandler(OnCompleted);
}
```
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. A lista das tarefas em segundo plano atualmente registradas pelo aplicativo é mantida na propriedade BackgroundTaskRegistration.AllTasks.

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