Definir condições para executar uma tarefa em segundo planoSet conditions for running a background task

APIs importantesImportant APIs

Saiba como definir condições que controlam quando a sua tarefa em segundo plano será executada.Learn how to set conditions that control when your background task will run.

Às vezes, tarefas em tela de fundo exigem que certas condições sejam atendidas para que possam ser concluídas com sucesso.Sometimes, background tasks require certain conditions to be met for the background task to succeed. Você pode definir uma ou mais das condições especificadas por SystemConditionType ao registrar sua tarefa em segundo plano.You can specify one or more of the conditions specified by SystemConditionType when registering your background task. A condição será verificada depois que o gatilho tiver sido disparado.The condition will be checked after the trigger has been fired. A tarefa em segundo plano será enfileirada, mas não será executada até que todas as condições necessárias sejam atendidas.The background task will then be queued, but it will not run until all the required conditions are satisfied.

Colocar condições em tarefas em segundo plano poupa bateria e CPU, evitando que as tarefas sejam executadas sem necessidade.Putting conditions on background tasks saves battery life and CPU by preventing tasks from running unnecessarily. Por exemplo, se a sua tarefa em segundo plano é executada com um temporizador e requer conectividade com a Internet, adicione a condição InternetAvailable a TaskBuilder antes de registrar a tarefa.For example, if your background task runs on a timer and requires Internet connectivity, add the InternetAvailable condition to the TaskBuilder before registering the task. Isso ajudará a evitar que a tarefa use recursos do sistema e duração da bateria desnecessariamente executando apenas a tarefa em segundo plano quando o temporizador tiver expirado e a Internet estiver disponível.This will help prevent the task from using system resources and battery life unnecessarily by only running the background task when the timer has elapsed and the Internet is available.

Também é possível combinar várias condições chamando addcondition várias vezes no mesmo TaskBuilder.It is also possible to combine multiple conditions by calling AddCondition multiple times on the same TaskBuilder. Tome cuidado para não adicionar condições conflitantes, como UserPresente UserNotPresent.Take care not to add conflicting conditions, such as UserPresent and UserNotPresent.

Criar um objeto SystemConditionCreate a SystemCondition object

Este tópico pressupõe que você tenha uma tarefa em segundo plano já associada ao aplicativo e que o aplicativo já inclua um código que cria um objeto BackgroundTaskBuilder que se chama taskBuilder.This topic assumes that you have a background task already associated with your app, and that your app already includes code that creates a BackgroundTaskBuilder object named taskBuilder. Consulte Criar e registrar uma tarefa em segundo plano no processo ou Criar e registrar uma tarefa em segundo plano fora do processo se você precisar criar uma tarefa em segundo plano primeiro.See Create and register an in-process background task or Create and register an out-of-process background task if you need to create a background task first.

Este tópico se aplica a tarefas em segundo plano executadas fora do processo, bem como àquelas executadas no mesmo processo do aplicativo em primeiro plano.This topic applies to background tasks that run out-of-process as well as those that run in the same process as the foreground app.

Antes de adicionar a condição, crie um objeto SystemCondition para representar a condição que precisa estar em vigor para uma tarefa em segundo plano ser executada.Before adding the condition, create a SystemCondition object to represent the condition that must be in effect for a background task to run. No construtor, especifique a condição que deve ser atendida com um valor de enumeração SystemConditionType.In the constructor, specify the condition that must be met with a SystemConditionType enumeration value.

O código a seguir cria um objeto SystemCondition que especifica a condição InternetAvailable:The following code creates a SystemCondition object that specifies the InternetAvailable condition:

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 à sua tarefa em segundo planoAdd the SystemCondition object to your background task

Para adicionar a condição, chame o método AddCondition no objeto BackgroundTaskBuilder e passe a ele o objeto SystemCondition.To add the condition, call the AddCondition method on the BackgroundTaskBuilder object, and pass it the SystemCondition object.

O código a seguir usa taskBuilder para adicionar a condição InternetAvailable.The following code uses taskBuilder to add the InternetAvailable condition.

taskBuilder.AddCondition(internetCondition);
taskBuilder.AddCondition(internetCondition);
taskBuilder->AddCondition(internetCondition);

Registrar sua tarefa em segundo planoRegister your background task

Agora, você pode registrar sua tarefa em segundo plano no método Register, e a tarefa em segundo plano não será iniciada até a condição especificada ser atendida.Now you can register your background task with the Register method, and the background task will not start until the specified condition is met.

O código a seguir registra a tarefa e armazena o objeto BackgroundTaskRegistration resultante:The following code registers the task and stores the resulting BackgroundTaskRegistration object:

BackgroundTaskRegistration task = taskBuilder.Register();
Windows::ApplicationModel::Background::BackgroundTaskRegistration task{ recurringTaskBuilder.Register() };
BackgroundTaskRegistration ^ task = taskBuilder->Register();

Observação

Os parâmetros de registro de tarefas em segundo plano são validados no momento do registro.Background task registration parameters are validated at the time of registration. Um erro será retornado se algum parâmetro de registro for inválido.An error is returned if any of the registration parameters are invalid. Verifique se o aplicativo trata tranquilamente cenários em que o registro de tarefas de segundo plano apresenta falha. Se, em vez disso, o aplicativo depender de ter um objeto de registro válido depois de tentar registrar uma tarefa, ele poderá travar.Ensure that your app gracefully handles scenarios where background task registration fails - if instead your app depends on having a valid registration object after attempting to register a task, it may crash.

Inserir várias condições na sua tarefa em segundo planoPlace multiple conditions on your background task

Para adicionar várias condições, seu aplicativo faz várias chamadas ao método AddCondition .To add multiple conditions, your app makes multiple calls to the AddCondition method. Essas chamadas devem ser feitas antes que o registro da tarefa se torne efetivo.These calls must come before task registration to be effective.

Observação

Tome cuidado para não adicionar condições conflitantes a uma tarefa em segundo plano.Take care not to add conflicting conditions to a background task.

O trecho a seguir mostra várias condições no contexto de criação e registro de uma tarefa em segundo plano.The following snippet shows multiple conditions in the context of creating and registering a background task.

// 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áriosRemarks

Observação

Escolha as condições da tarefa em segundo plano para que ela seja executada apenas quando for necessária e não seja executada quando ela não deveria.Choose conditions for your background task so that it only runs when it's needed, and doesn't run when it shouldn't. Confira SystemConditionType para ver descrições das diferentes condições de tarefas em tela de fundo.See SystemConditionType for descriptions of the different background task conditions.