Usar un desencadenador de mantenimientoUse a maintenance trigger

API importantesImportant APIs

Obtenga información sobre cómo usar la clase MaintenanceTrigger para ejecutar código ligero en segundo plano mientras el dispositivo está conectado.Learn how to use the MaintenanceTrigger class to run lightweight code in the background while the device is plugged in.

Crear un objeto de desencadenador de mantenimientoCreate a maintenance trigger object

En este ejemplo se da por hecho que tienes un código ligero que puedes ejecutar en segundo plano para mejorar la aplicación mientras el dispositivo está enchufado.This example assumes that you have lightweight code you can run in the background to enhance your app while the device is plugged in. Este tema se centra en la clase MaintenanceTrigger, que es similar a SystemTrigger.This topic focuses on the MaintenanceTrigger, which is similar to SystemTrigger.

Para obtener más información sobre cómo escribir una clase de tarea en segundo plano, consulta Crear y registrar una tarea en segundo plano dentro de proceso o Crear y registrar una tarea en segundo plano fuera de proceso.More information on writing a background task class is available in Create and register an in-process background task or Create and register an out-of-process background task.

Crea un nuevo objeto MaintenanceTrigger.Create a new MaintenanceTrigger object. El segundo parámetro, OneShot, especifica si la tarea de mantenimiento se ejecutará solo una vez o si seguirá ejecutándose periódicamente.The second parameter, OneShot, specifies whether the maintenance task will run only once or continue to run periodically. Si OneShot se establece en "true", el primer parámetro (FreshnessTime) especifica el número de minutos que se debe esperar antes de programar la tarea en segundo plano.If OneShot is set to true, the first parameter (FreshnessTime) specifies the number of minutes to wait before scheduling the background task. Si OneShot se establece en "false", FreshnessTime especifica la frecuencia con la que se ejecutará la tarea en segundo plano.If OneShot is set to false, FreshnessTime specifies how often the background task will run.

Nota

Si FreshnessTime se establece en menos de 15 minutos, se produce una excepción al intentar registrar la tarea en segundo plano.If FreshnessTime is set to less than 15 minutes, an exception is thrown when attempting to register the background task.

Este código de ejemplo crea un desencadenador que se ejecuta una vez por hora.This example code creates a trigger that runs once an hour.

uint waitIntervalMinutes = 60;
MaintenanceTrigger taskTrigger = new MaintenanceTrigger(waitIntervalMinutes, false);
uint32_t waitIntervalMinutes{ 60 };
Windows::ApplicationModel::Background::MaintenanceTrigger taskTrigger{ waitIntervalMinutes, false };
unsigned int waitIntervalMinutes = 60;
MaintenanceTrigger ^ taskTrigger = ref new MaintenanceTrigger(waitIntervalMinutes, false);

(Opcional) Agregar una condición(Optional) Add a condition

  • Si es necesario, crea una condición a la tarea en segundo plano para controlar cuándo debe ejecutarse la tarea.If necessary, create a background task condition to control when the task runs. Una condición evita que tu tarea en segundo plano se ejecute hasta que no se cumpla la condición. Para obtener más información, consulta Establecer condiciones para ejecutar una tarea en segundo plano.A condition prevents your background task from running until the condition is met - for more information, see Set conditions for running a background task

En este ejemplo, la condición se establece en InternetAvailable de forma que el mantenimiento se ejecuta cuando Internet está disponible (o cuando vuelva a estarlo).In this example, the condition is set to InternetAvailable so that maintenance runs when the Internet is available (or when it becomes available). Para obtener una lista de posibles condiciones de tareas en segundo plano, consulta SystemConditionType.For a list of possible background task conditions, see SystemConditionType.

El siguiente código agrega una condición al generador de tareas de mantenimiento:The following code adds a condition to the maintenance task builder:

SystemCondition exampleCondition = new SystemCondition(SystemConditionType.InternetAvailable);
Windows::ApplicationModel::Background::SystemCondition exampleCondition{
    Windows::ApplicationModel::Background::SystemConditionType::InternetAvailable };
SystemCondition ^ exampleCondition = ref new SystemCondition(SystemConditionType::InternetAvailable);

Registrar la tarea en segundo planoRegister the background task

  • Registra la tarea en segundo plano llamando a tu función de registro de tareas en segundo plano.Register the background task by calling your background task registration function. Para obtener más información sobre el registro de tareas en segundo plano, consulta Registrar una tarea en segundo plano.For more information on registering background tasks, see Register a background task.

El siguiente código registra la tarea de mantenimiento.The following code registers the maintenance task. Ten en cuenta que se supone que la tarea en segundo plano se ejecuta en un proceso independiente de la aplicación, ya que especifica el elemento entryPoint.Note that it assumes your background task runs in a separate process from your app because it specifies entryPoint. Si la tarea en segundo plano se ejecuta en el mismo proceso que la aplicación, no se especifica entryPoint.If your background task runs in the same process as your app, you do not specify entryPoint.

string entryPoint = "Tasks.ExampleBackgroundTaskClass";
string taskName   = "Maintenance background task example";

BackgroundTaskRegistration task = RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition);
std::wstring entryPoint{ L"Tasks.ExampleBackgroundTaskClass" };
std::wstring taskName{ L"Maintenance background task example" };

Windows::ApplicationModel::Background::BackgroundTaskRegistration task{
    RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition) };
String ^ entryPoint = "Tasks.ExampleBackgroundTaskClass";
String ^ taskName   = "Maintenance background task example";

BackgroundTaskRegistration ^ task = RegisterBackgroundTask(entryPoint, taskName, taskTrigger, exampleCondition);

Nota

Para todas las familias de dispositivos excepto la de equipos de escritorio, si el dispositivo dispone de poca memoria, las tareas en segundo plano podrían finalizarse.For all device families except desktop, if the device becomes low on memory, background tasks may be terminated. Si no se expone una excepción de falta de memoria o la aplicación no la controla, la tarea en segundo plano finalizará sin que se muestre ninguna advertencia y sin que se genere el evento OnCanceled.If an out of memory exception is not surfaced, or the app does not handle it, then the background task will be terminated without warning and without raising the OnCanceled event. Esto contribuye a garantizar la experiencia del usuario de la aplicación en primer plano.This helps to ensure the user experience of the app in the foreground. La tarea en segundo plano debe estar diseñada para controlar este escenario.Your background task should be designed to handle this scenario.

Nota

Plataforma universal de Windows aplicaciones deben llamar a RequestAccessAsync antes de registrar cualquiera de los tipos de desencadenadores en segundo plano.Universal Windows Platform apps must call RequestAccessAsync before registering any of the background trigger types.

Para garantizar que la aplicación universal de Windows continúe funcionando correctamente después de publicar una actualización de la aplicación, se debe llamar a RemoveAccess y a continuación a RequestAccessAsync una vez iniciada la aplicación tras su actualización.To ensure that your Universal Windows app continues to run properly after you release an update to your app, you must call RemoveAccess and then call RequestAccessAsync when your app launches after being updated. Para obtener más información, vea instrucciones para tareas en segundo plano.For more information, see Guidelines for background tasks.

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.