Inscrire une tâche en arrière-planRegister a background task

API importantesImportant APIs

Découvrez comment créer une fonction que vous pouvez réutiliser pour inscrire la plupart des tâches en arrière-plan en toute sécurité.Learn how to create a function that can be re-used to safely register most background tasks.

Cette rubrique s’applique aussi bien aux tâches en arrière-plan in-process qu’aux tâches en arrière-plan hors processus.This topic is applicable to both in-process background tasks and out-of-process background tasks. Cette rubrique suppose que vous disposez déjà d’une tâche en arrière-plan nécessitant une inscription.This topic assumes that you already have a background task that needs to be registered. (Consultez les rubriques Créer et inscrire une tâche en arrière-plan hors processus ou Créer et inscrire une tâche en arrière-plan in-process pour découvrir comment écrire une tâche en arrière-plan).(See Create and register a background task that runs out-of-process or Create and register an in-process background task for information about how to write a background task).

Cette rubrique décrit une fonction utilitaire chargée d’inscrire les tâches en arrière-plan.This topic walks through a utility function that registers background tasks. Pour éviter tout problème avec de multiples inscriptions, cette fonction utilitaire recherche d’abord des inscriptions existantes avant d’inscrire la tâche plusieurs fois. Elle peut aussi appliquer une condition système à la tâche en arrière-plan.This utility function checks for existing registrations first before registering the task multiple times to avoid problems with multiple registrations, and it can apply a system condition to the background task. La procédure pas à pas inclut un exemple de mise en pratique exhaustif de cette fonction utilitaire.The walkthrough includes a complete, working example of this utility function.

RemarqueNote  

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

Pour vous assurer que votre application Windows universelle continue de s’exécuter correctement après la publication d’une mise à jour, vous devez appeler RemoveAccess, puis RequestAccessAsync lorsque votre application est lancée après avoir été mise à jour.To ensure that your Universal Windows app continues to run properly after you release an update, 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.

Définir la signature de la méthode et le type de retourDefine the method signature and return type

Cette méthode contient le point d’entrée de la tâche, son nom, un déclencheur de tâche en arrière-plan créé à l’avance et un objet SystemCondition pour la tâche en arrière-plan (facultatif).This method takes in the task entry point, task name, a pre-constructed background task trigger, and (optionally) a SystemCondition for the background task. Cette méthode retourne un objet BackgroundTaskRegistration .This method returns a BackgroundTaskRegistration object.

Important

taskEntryPoint -pour les tâches en arrière-plan qui s’exécutent dans un processus hors processus, il doit être construit comme nom d’espace de noms, '. 'et le nom de la classe contenant votre classe d’arrière-plan.taskEntryPoint - for background tasks that run in out of process, this must be constructed as the namespace name, '.', and the name of the class containing your background class. La chaîne est sensible à la casse.The string is case-sensitive. Par exemple, si vous avez un espace de noms « MyBackgroundTasks » et une classe « BackgroundTask1 » qui contenait votre code de classe d’arrière-plan, la chaîne de taskEntryPoint serait « MyBackgroundTasks. BackgroundTask1 ».For example, if you had a namespace "MyBackgroundTasks" and a class "BackgroundTask1" that contained your background class code, the string for taskEntryPoint would be "MyBackgroundTasks.BackgroundTask1". Si votre tâche en arrière-plan s’exécute dans le même processus que votre application (c’est-à-dire dans le cas d’une tâche en arrière-plan in-process), la chaîne taskEntryPoint ne doit pas être définie.If your background task runs in the same process as your app (i.e. a in-process background task) taskEntryPoint should not be set.

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    
    // We'll add code to this function in subsequent steps.

}
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{
    
    // We'll add code to this function in subsequent steps.

}

Rechercher des inscriptions existantesCheck for existing registrations

Vérifiez si la tâche est déjà inscrite.Check whether the task is already registered. Cette vérification est primordiale car, si la tâche est inscrite plusieurs fois, elle sera exécutée plusieurs fois à chaque fois qu’elle est déclenchée, ce qui peut aboutir à une utilisation excessive du processeur et entraîner un comportement inattendu.It's important to check this because if a task is registered multiple times, it will run more than once whenever it’s triggered; this can use excess CPU and may cause unexpected behavior.

Vous pouvez rechercher les inscriptions existantes en interrogeant la propriété BackgroundTaskRegistration. AllTasks et en effectuant une itération sur le résultat.You can check for existing registrations by querying the BackgroundTaskRegistration.AllTasks property and iterating on the result. Vérifiez le nom de chaque instance. S’il correspond au nom de la tâche que vous inscrivez, sortez de la boucle et définissez une variable d’indicateur afin que votre code puisse choisir un chemin différent lors de la prochaine étape.Check the name of each instance – if it matches the name of the task you’re registering, then break out of the loop and set a flag variable so that your code can choose a different path in the next step.

Remarque    Utilisez des noms de tâches en arrière-plan qui sont propres à votre application.Note  Use background task names that are unique to your app. Assurez-vous que chaque tâche en arrière-plan possède un nom unique.Ensure each background task has a unique name.

Le code suivant inscrit une tâche en arrière-plan à l’aide du événement systemtrigger que nous avons créé à la dernière étape :The following code registers a background task using the SystemTrigger we created in the last step:

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == name)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }
    
    // We'll register the task in the next step.
}
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{
    //
    // Check for existing registrations of this background task.
    //
    
    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;
    
    while (hascur)
    {
        auto cur = iter->Current->Value;
        
        if(cur->Name == name)
        {
            //
            // The task is registered.
            //
            
            return (BackgroundTaskRegistration ^)(cur);
        }
        
        hascur = iter->MoveNext();
    }
    
    // We'll register the task in the next step.
}

Inscrire la tâche en arrière-plan (ou renvoyer l’inscription existante)Register the background task (or return the existing registration)

Vérifiez si la tâche a été trouvée dans la liste des inscriptions de tâches en arrière-plan existantes.Check to see if the task was found in the list of existing background task registrations. Dans l’affirmative, renvoyez cette instance de la tâche.If so, return that instance of the task.

Inscrivez ensuite la tâche à l’aide d’un nouvel objet BackgroundTaskBuilder.Then, register the task using a new BackgroundTaskBuilder object. Le code doit vérifier si le paramètre de condition est Null. Si cela n’est pas le cas, ajoutez la condition à l’objet d’inscription.This code should check whether the condition parameter is null, and if not, add the condition to the registration object. Retourne le BackgroundTaskRegistration retourné par la méthode BackgroundTaskBuilder. Register .Return the BackgroundTaskRegistration returned by the BackgroundTaskBuilder.Register method.

Remarque    Les paramètres d’inscription des tâches en arrière-plan sont validés au moment de l’inscription.Note  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. Remarque Si vous inscrivez une tâche en arrière-plan qui s’exécute dans le même processus que votre application, envoyez String.Empty ou null pour le paramètre taskEntryPoint.Note If you are registering a background task that runs in the same process as your app, send String.Empty or null for the taskEntryPoint parameter.

L’exemple suivant renvoie la tâche existante ou bien ajoute le code chargé d’inscrire la tâche en arrière-plan (y compris la condition système facultative si elle est fournie) :The following example either returns the existing task, or adds code that registers the background task (including the optional system condition if present):

public static BackgroundTaskRegistration RegisterBackgroundTask(
                                                string taskEntryPoint,
                                                string name,
                                                IBackgroundTrigger trigger,
                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == taskName)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }

    //
    // Register the background task.
    //

    var builder = new BackgroundTaskBuilder();

    builder.Name = name;

    // in-process background tasks don't set TaskEntryPoint
    if ( taskEntryPoint != null && taskEntryPoint != String.Empty)
    {
        builder.TaskEntryPoint = taskEntryPoint;
    }
    builder.SetTrigger(trigger);

    if (condition != null)
    {
        builder.AddCondition(condition);
    }

    BackgroundTaskRegistration task = builder.Register();

    return task;
}
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(
                                             Platform::String ^ taskEntryPoint,
                                             Platform::String ^ taskName,
                                             IBackgroundTrigger ^ trigger,
                                             IBackgroundCondition ^ condition)
{

    //
    // Check for existing registrations of this background task.
    //

    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;

    while (hascur)
    {
        auto cur = iter->Current->Value;

        if(cur->Name == name)
        {
            //
            // The task is registered.
            //

            return (BackgroundTaskRegistration ^)(cur);
        }

        hascur = iter->MoveNext();
    }

    //
    // Register the background task.
    //

    auto builder = ref new BackgroundTaskBuilder();

    builder->Name = name;
    builder->TaskEntryPoint = taskEntryPoint;
    builder->SetTrigger(trigger);

    if (condition != nullptr) {
        
        builder->AddCondition(condition);
    }

    BackgroundTaskRegistration ^ task = builder->Register();

    return task;
}

Fonction utilitaire d’inscription des tâches en arrière-plan terminéeComplete background task registration utility function

Cet exemple montre la fonction d’inscription des tâches en arrière-plan parvenue à son terme.This example shows the completed background task registration function. Vous pouvez vous servir de cette fonction pour inscrire la plupart des tâches en arrière-plan, à l’exception des tâches en arrière-plan réseau.This function can be used to register most background tasks, with the exception of networking background tasks.

//
// Register a background task with the specified taskEntryPoint, name, trigger,
// and condition (optional).
//
// taskEntryPoint: Task entry point for the background task.
// taskName: A name for the background task.
// trigger: The trigger for the background task.
// condition: Optional parameter. A conditional event that must be true for the task to fire.
//
public static BackgroundTaskRegistration RegisterBackgroundTask(string taskEntryPoint,
                                                                string taskName,
                                                                IBackgroundTrigger trigger,
                                                                IBackgroundCondition condition)
{
    //
    // Check for existing registrations of this background task.
    //

    foreach (var cur in BackgroundTaskRegistration.AllTasks)
    {

        if (cur.Value.Name == taskName)
        {
            //
            // The task is already registered.
            //

            return (BackgroundTaskRegistration)(cur.Value);
        }
    }

    //
    // Register the background task.
    //

    var builder = new BackgroundTaskBuilder();

    builder.Name = taskName;
    builder.TaskEntryPoint = taskEntryPoint;
    builder.SetTrigger(trigger);

    if (condition != null)
    {

        builder.AddCondition(condition);
    }

    BackgroundTaskRegistration task = builder.Register();

    return task;
}
//
// Register a background task with the specified taskEntryPoint, name, trigger,
// and condition (optional).
//
// taskEntryPoint: Task entry point for the background task.
// taskName: A name for the background task.
// trigger: The trigger for the background task.
// condition: Optional parameter. A conditional event that must be true for the task to fire.
//
BackgroundTaskRegistration^ MainPage::RegisterBackgroundTask(Platform::String ^ taskEntryPoint,
                                                             Platform::String ^ taskName,
                                                             IBackgroundTrigger ^ trigger,
                                                             IBackgroundCondition ^ condition)
{

    //
    // Check for existing registrations of this background task.
    //

    auto iter   = BackgroundTaskRegistration::AllTasks->First();
    auto hascur = iter->HasCurrent;

    while (hascur)
    {
        auto cur = iter->Current->Value;

        if(cur->Name == name)
        {
            //
            // The task is registered.
            //

            return (BackgroundTaskRegistration ^)(cur);
        }

        hascur = iter->MoveNext();
    }


    //
    // Register the background task.
    //

    auto builder = ref new BackgroundTaskBuilder();

    builder->Name = name;
    builder->TaskEntryPoint = taskEntryPoint;
    builder->SetTrigger(trigger);

    if (condition != nullptr) {

        builder->AddCondition(condition);
    }

    BackgroundTaskRegistration ^ task = builder->Register();

    return task;
}