Utiliser un déclencheur de maintenanceUse a maintenance trigger

API importantesImportant APIs

Découvrez comment utiliser la classe MaintenanceTrigger pour exécuter du code léger en arrière-plan pendant que l’appareil est branché.Learn how to use the MaintenanceTrigger class to run lightweight code in the background while the device is plugged in.

Créer un objet déclencheur de maintenanceCreate a maintenance trigger object

Cet exemple suppose que vous disposez d’un code léger à exécuter en arrière-plan qui vous permettra d’améliorer votre application pendant que l’appareil est branché.This example assumes that you have lightweight code you can run in the background to enhance your app while the device is plugged in. Cette rubrique porte sur le déclencheur MaintenanceTrigger, qui est semblable au déclencheur SystemTrigger.This topic focuses on the MaintenanceTrigger, which is similar to SystemTrigger.

Des informations supplémentaires sur l’écriture d’une classe de tâche en arrière-plan sont disponibles dans les rubriques Créer et inscrire une tâche en arrière-plan in-process ou Créer et inscrire une tâche en arrière-plan hors processus.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.

Créez un nouvel objet MaintenanceTrigger .Create a new MaintenanceTrigger object. Le deuxième paramètre, OneShot, indique si la tâche de maintenance s’exécute une seule fois ou régulièrement.The second parameter, OneShot, specifies whether the maintenance task will run only once or continue to run periodically. Si OneShot est défini sur true, le premier paramètre (FreshnessTime) indique le nombre de minutes à attendre avant de planifier la tâche en arrière-plan.If OneShot is set to true, the first parameter (FreshnessTime) specifies the number of minutes to wait before scheduling the background task. Si OneShot est défini sur false, FreshnessTime indique la fréquence d’exécution de la tâche en arrière-plan.If OneShot is set to false, FreshnessTime specifies how often the background task will run.

Notes

Si FreshnessTime a une valeur inférieure à 15 minutes, une exception est levée lors de la tentative d’inscription de la tâche en arrière-plan.If FreshnessTime is set to less than 15 minutes, an exception is thrown when attempting to register the background task.

Cet exemple de code crée un déclencheur qui s’exécute une fois par heure.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);

(Facultatif) Ajouter une condition(Optional) Add a condition

  • Si besoin est, créez une condition de tâche en arrière-plan afin de contrôler le moment où la tâche est exécutée.If necessary, create a background task condition to control when the task runs. Une condition empêche votre tâche en arrière-plan de s’exécuter tant que la condition n’est pas satisfaite. Pour plus d’informations, voir Définir des conditions pour exécuter une tâche en arrière-plan.A condition prevents your background task from running until the condition is met - for more information, see Set conditions for running a background task

Dans cet exemple, la condition est définie sur InternetAvailable, de sorte que la maintenance s’exécute quand Internet est accessible (ou le devient).In this example, the condition is set to InternetAvailable so that maintenance runs when the Internet is available (or when it becomes available). Pour obtenir la liste des conditions de tâche d’arrière-plan possibles, consultez SystemConditionType.For a list of possible background task conditions, see SystemConditionType.

Le code suivant ajoute une condition au générateur de tâches de maintenance :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);

Inscrire la tâche en arrière-planRegister the background task

  • Inscrivez la tâche en arrière-plan en appelant la fonction qui vous permet de le faire.Register the background task by calling your background task registration function. Pour plus d’informations sur l’inscription des tâches en arrière-plan, voir Inscrire une tâche en arrière-plan.For more information on registering background tasks, see Register a background task.

Le code suivant inscrit la tâche de maintenance.The following code registers the maintenance task. Notez qu’il part du principe que votre tâche en arrière-plan s’exécute dans un processus distinct de celui de votre application, car il spécifie entryPoint.Note that it assumes your background task runs in a separate process from your app because it specifies entryPoint. Si votre tâche en arrière-plan s’exécute dans le même processus que votre application, vous ne devez pas spécifier 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);

Notes

Pour toutes les familles d’appareils, à l’exception des ordinateurs de bureau, les tâches en arrière-plan peuvent être arrêtées en cas de mémoire insuffisante de l’appareil.For all device families except desktop, if the device becomes low on memory, background tasks may be terminated. Si aucune exception de mémoire insuffisante n’est exposée ou si l’application ne la gère pas, la tâche en arrière-plan est alors arrêtée sans avertissement ni déclenchement de l’événement 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. Cela permet de garantir l’expérience utilisateur de l’application au premier plan.This helps to ensure the user experience of the app in the foreground. Votre tâche en arrière-plan doit être conçue de manière à gérer ce scénario.Your background task should be designed to handle this scenario.

Notes

Plateforme Windows universelle applications doivent appeler RequestAccessAsync avant d’inscrire l’un des types de déclencheurs d’arrière-plan.Universal Windows Platform apps must call RequestAccessAsync before registering any of the background trigger types.

Pour vous assurer que votre application Windows universelle continue à s’exécuter correctement après la publication d’une mise à jour de votre application, vous devez appeler RemoveAccess , puis appeler RequestAccessAsync lorsque votre application est lancée après sa mise à jour.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. Pour plus d’informations, voir Recommandations en matière de tâches en arrière-plan.For more information, see Guidelines for background tasks.

Notes

Les paramètres d’inscription de la tâche en arrière-plan sont validés au moment de l’inscription.Background task registration parameters are validated at the time of registration. Si l’un des paramètres d’inscription n’est pas valide, une erreur est renvoyée.An error is returned if any of the registration parameters are invalid. Vérifiez que votre application gère de manière fluide les scénarios dans lesquels l’inscription de la tâche en arrière-plan échoue. En revanche, si votre application dépend d’un objet d’inscription valide après la tentative d’inscription d’une tâche, elle peut se bloquer.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.