Definir condições para executar uma tarefa em segundo plano

  • Artigo

APIs importantes

Saiba como definir condições que controlam quando a sua tarefa em segundo plano será executada.

Às vezes, as tarefas em segundo plano exigem que determinadas condições sejam atendidas para que a tarefa em segundo plano seja bem-sucedida. Você pode especificar uma ou mais das condições especificadas por SystemConditionType ao registrar sua tarefa em segundo plano. A condição será verificada depois que o gatilho for disparado. A tarefa em segundo plano será enfileirada, mas não será executada até que todas as condições necessárias sejam atendidas.

Colocar condições em tarefas em segundo plano economiza bateria e CPU, impedindo que as tarefas sejam executadas desnecessariamente. Por exemplo, se sua tarefa em segundo plano for executada em um temporizador e exigir conectividade com a Internet, adicione a condição InternetAvailable ao TaskBuilder antes de registrar a tarefa. Isso ajudará a evitar que a tarefa use recursos do sistema e a duração da bateria desnecessariamente, executando a tarefa em segundo plano apenas quando o cronômetro tiver decorrido e a Internet estiver disponível.

Também é possível combinar várias condições chamando AddCondition várias vezes no mesmo TaskBuilder. Tome cuidado para não adicionar condições conflitantes, como UserPresent e UserNotPresent.

Criar um objeto SystemCondition

Este tópico pressupõe que você já tenha uma tarefa em segundo plano associada ao seu aplicativo e que seu aplicativo já inclua código que cria um objeto BackgroundTaskBuilder chamado taskBuilder. Consulte Criar e registrar uma tarefa em segundo plano em processo ou Criar e registrar uma tarefa em segundo plano fora do processo se precisar criar uma tarefa em segundo plano primeiro.

Este tópico se aplica a tarefas em segundo plano que são executadas fora do processo, bem como aquelas que são executadas no mesmo processo que o aplicativo em primeiro plano.

Antes de adicionar a condição, crie um objeto SystemCondition para representar a condição que deve estar em vigor para que uma tarefa em segundo plano seja executada. No construtor, especifique a condição que deve ser atendida com um valor de enumeração SystemConditionType.

O código a seguir cria um objeto SystemCondition que especifica a condição InternetAvailable:

SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);

Windows::ApplicationModel::Background::SystemCondition internetCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };

SystemCondition ^ internetCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);

Adicionar o objeto SystemCondition à tarefa em segundo plano

Para adicionar a condição, chame o método AddCondition no objeto BackgroundTaskBuilder e passe a ele o objeto SystemCondition.

O código a seguir usa taskBuilder para adicionar a condição InternetAvailable .

taskBuilder.AddCondition(internetCondition);

taskBuilder.AddCondition(internetCondition);

taskBuilder->AddCondition(internetCondition);

Registrar sua tarefa em segundo plano

Agora você pode registrar sua tarefa em segundo plano com o método Register e a tarefa em segundo plano não será iniciada até que a condição especificada seja atendida.

O código a seguir registra a tarefa e armazena o objeto BackgroundTaskRegistration resultante:

BackgroundTaskRegistration task = taskBuilder.Register();

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{ recurringTaskBuilder.Register() };

BackgroundTaskRegistration ^ task = taskBuilder->Register();

Observação

Os parâmetros de registro de tarefa em segundo plano são validados no momento do registro. Um erro será retornado se qualquer um dos parâmetros de registro for inválido. Certifique-se de que seu aplicativo lide normalmente com cenários em que o registro de tarefa em segundo plano falha – se, em vez disso, seu aplicativo depender de ter um objeto de registro válido depois de tentar registrar uma tarefa, ele poderá falhar.

Colocar várias condições em sua tarefa em segundo plano

Para adicionar várias condições, seu aplicativo faz várias chamadas para o método AddCondition . Essas chamadas devem vir antes do registro da tarefa para serem efetivas.

Observação

Tome cuidado para não adicionar condições conflitantes a uma tarefa em segundo plano.

O snippet a seguir mostra várias condições no contexto da criação e do registro de uma tarefa em segundo plano.

// Set up the background task.
TimeTrigger hourlyTrigger = new TimeTrigger(60, false);

var recurringTaskBuilder = new BackgroundTaskBuilder();

recurringTaskBuilder.Name           = "Hourly background task";
recurringTaskBuilder.TaskEntryPoint = "Tasks.ExampleBackgroundTaskClass";
recurringTaskBuilder.SetTrigger(hourlyTrigger);

// Begin adding conditions.
SystemCondition userCondition     = new SystemCondition(SystemConditionType.UserPresent);
SystemCondition internetCondition = new SystemCondition(SystemConditionType.InternetAvailable);

recurringTaskBuilder.AddCondition(userCondition);
recurringTaskBuilder.AddCondition(internetCondition);

// Done adding conditions, now register the background task.

BackgroundTaskRegistration task = recurringTaskBuilder.Register();

// Set up the background task.
Windows::ApplicationModel::Background::TimeTrigger hourlyTrigger{ 60, false };

Windows::ApplicationModel::Background::BackgroundTaskBuilder recurringTaskBuilder;

recurringTaskBuilder.Name(L"Hourly background task");
recurringTaskBuilder.TaskEntryPoint(L"Tasks.ExampleBackgroundTaskClass");
recurringTaskBuilder.SetTrigger(hourlyTrigger);

// Begin adding conditions.
Windows::ApplicationModel::Background::SystemCondition userCondition{
    Windows::ApplicationModel::Background::SystemConditionType::UserPresent };
Windows::ApplicationModel::Background::SystemCondition internetCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };

recurringTaskBuilder.AddCondition(userCondition);
recurringTaskBuilder.AddCondition(internetCondition);

// Done adding conditions, now register the background task.
Windows::ApplicationModel::Background::BackgroundTaskRegistration task{ recurringTaskBuilder.Register() };

// Set up the background task.
TimeTrigger ^ hourlyTrigger = ref new TimeTrigger(60, false);

auto recurringTaskBuilder = ref new BackgroundTaskBuilder();

recurringTaskBuilder->Name           = "Hourly background task";
recurringTaskBuilder->TaskEntryPoint = "Tasks.ExampleBackgroundTaskClass";
recurringTaskBuilder->SetTrigger(hourlyTrigger);

// Begin adding conditions.
SystemCondition ^ userCondition     = ref new SystemCondition(SystemConditionType::UserPresent);
SystemCondition ^ internetCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);

recurringTaskBuilder->AddCondition(userCondition);
recurringTaskBuilder->AddCondition(internetCondition);

// Done adding conditions, now register the background task.
BackgroundTaskRegistration ^ task = recurringTaskBuilder->Register();

Comentários

Observação

Escolha condições para sua tarefa em segundo plano para que ela seja executada apenas quando for necessária e não seja executada quando não deveria. Consulte SystemConditionType para obter descrições das diferentes condições de tarefa em segundo plano.