Définir des conditions pour exécuter une tâche en arrière-planSet conditions for running a background task

API importantesImportant APIs

Découvrez comment définir des conditions qui contrôlent le moment auquel votre tâche en arrière-plan s’exécutera.Learn how to set conditions that control when your background task will run.

Parfois, les tâches en arrière-plan requièrent que certaines conditions soient remplies pour que la tâche en arrière-plan aboutisse.Sometimes, background tasks require certain conditions to be met for the background task to succeed. Vous pouvez spécifier une ou plusieurs des conditions spécifiées par SystemConditionType au moment d’inscrire votre tâche en arrière-plan.You can specify one or more of the conditions specified by SystemConditionType when registering your background task. La condition est vérifiée une fois que le déclencheur a été activé.The condition will be checked after the trigger has been fired. La tâche en arrière-plan est ensuite mise en file d’attente, mais elle ne s’exécute pas tant que toutes les conditions requises ne sont pas satisfaites.The background task will then be queued, but it will not run until all the required conditions are satisfied.

Le fait de placer des conditions sur des tâches en arrière-plan économise la durée de vie de la batterie et le processeur en empêchant l’exécution inutilePutting conditions on background tasks saves battery life and CPU by preventing tasks from running unnecessarily. Par exemple, si votre tâche en arrière-plan est exécutée sur un minuteur et nécessite une connectivité Internet, ajoutez la condition InternetAvailable au TaskBuilder avant d’inscrire la tâche.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. Cela empêchera ainsi la tâche de faire inutilement appel aux ressources système et à l’autonomie de la batterie. Elle s’exécutera uniquement une fois que le minuteur sera arrivé à expiration et qu’Internet sera accessible.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.

Il est également possible de combiner plusieurs conditions en appelant plusieurs fois AddCondition sur le même TaskBuilder.It is also possible to combine multiple conditions by calling AddCondition multiple times on the same TaskBuilder. Veillez à ne pas ajouter de conditions conflictuelles, telles que UserPresent et UserNotPresent.Take care not to add conflicting conditions, such as UserPresent and UserNotPresent.

Créer un objet SystemConditionCreate a SystemCondition object

Cette rubrique suppose qu’une tâche en arrière-plan est déjà associée à votre application et que cette dernière comporte déjà du code qui crée un objet BackgroundTaskBuilder nommé 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. Consultez 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 si vous devez commencer par créer une tâche en arrière-plan.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.

Cette rubrique concerne aussi bien les tâches en arrière-plan qui s’exécutent hors processus que celles qui s’exécutent dans le même processus que l’application au premier plan.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.

Avant d’ajouter la condition, créez un objet SystemCondition pour représenter la condition qui doit être appliquée pour qu’une tâche en arrière-plan s’exécute.Before adding the condition, create a SystemCondition object to represent the condition that must be in effect for a background task to run. Dans le constructeur, spécifiez la condition qui doit être remplie avec une valeur d’énumération SystemConditionType .In the constructor, specify the condition that must be met with a SystemConditionType enumeration value.

Le code suivant crée un objet SystemCondition qui spécifie la condition 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);

Ajouter l’objet SystemCondition à votre tâche en arrière-planAdd the SystemCondition object to your background task

Pour ajouter la condition, appelez la méthode AddCondition sur l’objet BackgroundTaskBuilder et transmettez-lui l’objet SystemCondition .To add the condition, call the AddCondition method on the BackgroundTaskBuilder object, and pass it the SystemCondition object.

Le code suivant utilise taskBuilder pour ajouter la condition InternetAvailable .The following code uses taskBuilder to add the InternetAvailable condition.

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

Inscrire votre tâche en arrière-planRegister your background task

Vous pouvez maintenant inscrire votre tâche en arrière-plan à l’aide de la méthode Register , et la tâche en arrière-plan ne démarrera pas tant que la condition spécifiée n’est pas remplie.Now you can register your background task with the Register method, and the background task will not start until the specified condition is met.

Le code suivant inscrit la tâche et stocke l’objet BackgroundTaskRegistration obtenu :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();

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.

Placer plusieurs conditions dans la tâche en arrière-planPlace multiple conditions on your background task

Pour ajouter plusieurs conditions, votre application effectue plusieurs appels à la méthode AddCondition.To add multiple conditions, your app makes multiple calls to the AddCondition method. Pour être effectifs, ces appels doivent intervenir avant l’inscription de la tâche.These calls must come before task registration to be effective.

Notes

Veillez à ne pas ajouter de conditions conflictuelles à une tâche en arrière-plan.Take care not to add conflicting conditions to a background task.

L’extrait de code suivant montre plusieurs conditions dans le contexte de la création et de l’inscription d’une tâche en arrière-plan.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();

RemarquesRemarks

Notes

Choisissez des conditions pour votre tâche en arrière-plan afin qu’elle s’exécute uniquement lorsqu’elle est nécessaire, et ne s’exécute pas dans le cas contraire.Choose conditions for your background task so that it only runs when it's needed, and doesn't run when it shouldn't. Pour obtenir une description des différentes conditions de tâche en arrière-plan, consultez SystemConditionType .See SystemConditionType for descriptions of the different background task conditions.