Establecer condiciones para ejecutar una tarea en segundo planoSet conditions for running a background task

API importantesImportant APIs

Aprende a establecer condiciones que controlen cuándo se ejecutará tu tarea en segundo plano.Learn how to set conditions that control when your background task will run.

A veces, las tareas en segundo plano requieren que se cumplan ciertas condiciones para que la tarea en segundo plano se realice correctamente.Sometimes, background tasks require certain conditions to be met for the background task to succeed. Puedes especificar una o más de las condiciones especificadas por SystemConditionType al registrar tu tarea en segundo plano.You can specify one or more of the conditions specified by SystemConditionType when registering your background task. La condición se comprobará una vez que se haya activado el desencadenador.The condition will be checked after the trigger has been fired. La tarea en segundo plano se pondrá en cola, pero no se ejecutará hasta que se cumplan todas las condiciones necesarias.The background task will then be queued, but it will not run until all the required conditions are satisfied.

La colocación de condiciones en tareas en segundo plano ahorra batería y CPU al impedir que las tareas se ejecuten innecesariamente.Putting conditions on background tasks saves battery life and CPU by preventing tasks from running unnecessarily. Por ejemplo, si una tarea en segundo plano se ejecuta en un temporizador y requiere conectividad a Internet, agrega la condición InternetAvailable al TaskBuilder antes de registrar la tarea.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. Esto ayudará a impedir que la tarea use recursos del sistema y consuma batería de forma innecesaria al ejecutarse en segundo plano solo cuando haya transcurrido el temporizador e Internet esté disponible.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.

También es posible combinar varias condiciones llamando a AddCondition varias veces en el mismo TaskBuilder.It is also possible to combine multiple conditions by calling AddCondition multiple times on the same TaskBuilder. Procura no agregar condiciones conflictivas, como UserPresent y UserNotPresent.Take care not to add conflicting conditions, such as UserPresent and UserNotPresent.

Crear un objeto SystemConditionCreate a SystemCondition object

En este tema se supone que ya tiene una tarea en segundo plano asociada a la aplicación y que la aplicación ya incluye código que crea un objeto BackgroundTaskBuilder denominado 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. Consulta Crear y registrar una tarea en segundo plano dentro de proceso o Crear y registrar una tarea en segundo plano fuera de proceso si necesitas crear primero una tarea en segundo plano.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 tema se aplica a las tareas en segundo plano que se ejecutan fuera de proceso, así como las que se ejecutan en el mismo proceso que la aplicación en primer 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 agregar la condición, cree un objeto SystemCondition para representar la condición que debe estar activa para que se ejecute una tarea en segundo plano.Before adding the condition, create a SystemCondition object to represent the condition that must be in effect for a background task to run. En el constructor, especifique la condición que se debe cumplir con un valor de enumeración SystemConditionType .In the constructor, specify the condition that must be met with a SystemConditionType enumeration value.

En el código siguiente se crea un objeto SystemCondition que especifica la condición 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);

Agregar el objeto SystemCondition a la tarea en segundo planoAdd the SystemCondition object to your background task

Para agregar una condición, llama al método AddCondition en el objeto BackgroundTaskBuilder y pásalo al objeto SystemCondition.To add the condition, call the AddCondition method on the BackgroundTaskBuilder object, and pass it the SystemCondition object.

En el código siguiente se usa taskBuilder para agregar la condición InternetAvailable .The following code uses taskBuilder to add the InternetAvailable condition.

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

Registrar tu tarea en segundo planoRegister your background task

Ahora puede registrar la tarea en segundo plano con el método Register y la tarea en segundo plano no se iniciará hasta que se cumpla la condición especificada.Now you can register your background task with the Register method, and the background task will not start until the specified condition is met.

El siguiente código registra la tarea y almacena el 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();

Nota

Los parámetros de registro de tareas en segundo plano se validan en el momento en que se realiza el registro.Background task registration parameters are validated at the time of registration. Se devuelve un error si cualquiera de los parámetros de registro no es válido.An error is returned if any of the registration parameters are invalid. Asegúrate de que la aplicación se ocupe correctamente de los escenarios en los que se produce un error en el registro de tareas en segundo plano. Si, en cambio, la aplicación depende de que haya un objeto de registro válido después de intentar registrar una tarea, es posible que se bloquee.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.

Colocar varias condiciones en tu tarea en segundo planoPlace multiple conditions on your background task

Para agregar varias condiciones, tu aplicación realiza varias llamadas al método AddCondition .To add multiple conditions, your app makes multiple calls to the AddCondition method. Estas llamadas deben recibirse antes de que el registro de la tarea entre en vigor.These calls must come before task registration to be effective.

Nota

Tenga cuidado de no agregar condiciones en conflicto a una tarea en segundo plano.Take care not to add conflicting conditions to a background task.

En el fragmento de código siguiente se muestran varias condiciones en el contexto de la creación y el registro de una tarea en 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();

ObservacionesRemarks

Nota

Elija las condiciones de la tarea en segundo plano para que solo se ejecute cuando sea necesario y no se ejecute cuando no sea necesario.Choose conditions for your background task so that it only runs when it's needed, and doesn't run when it shouldn't. Consulta SystemConditionType para obtener descripciones de las diferentes condiciones de las tareas en segundo plano.See SystemConditionType for descriptions of the different background task conditions.