Inscrire une tâche en arrière-plan

API importantes

• Classe BackgroundTaskRegistration
• Classe BackgroundTaskBuilder
• Classe SystemCondition

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é.

Cette rubrique s’applique aux tâches en arrière-plan in-process et aux tâches en arrière-plan hors processus. Cette rubrique suppose que vous disposez déjà d’une tâche en arrière-plan qui doit être inscrite. (Voir Créez et inscrivez une tâche en arrière-plan qui s’exécute hors processus ou créez et inscrivez une tâche en arrière-plan in-process pour plus d’informations sur l’écriture d’une tâche en arrière-plan).

Cette rubrique décrit une fonction utilitaire qui inscrit des tâches en arrière-plan. Cette fonction utilitaire vérifie d’abord les inscriptions existantes avant d’inscrire la tâche plusieurs fois pour éviter les problèmes liés à plusieurs inscriptions, et elle peut appliquer une condition système à la tâche en arrière-plan. La procédure pas à pas inclut un exemple complet et fonctionnel de cette fonction utilitaire.

Remarque  

Les applications Windows universelles doivent appeler RequestAccessAsync avant d’inscrire l’un des types de déclencheurs en arrière-plan.

Pour vous assurer que votre application Windows universelle continue de s’exécuter correctement après avoir publié une mise à jour, vous devez appeler RemoveAccess, puis appeler RequestAccessAsync lorsque votre application démarre après avoir été mise à jour. Pour plus d’informations, consultez Instructions pour les tâches en arrière-plan.

Définir la signature de méthode et le type de retour

Cette méthode prend le point d’entrée de tâche, le nom de la tâche, un déclencheur de tâche en arrière-plan prédéfinit et (éventuellement) un SystemCondition pour la tâche en arrière-plan. Cette méthode retourne un objet BackgroundTaskRegistration.

Important

taskEntryPoint - pour les tâches en arrière-plan qui s’exécutent en dehors du processus, elles doivent être construites en tant que nom d’espace de noms, « . » et nom de la classe contenant votre classe d’arrière-plan. La chaîne respecte la casse. Par exemple, si vous aviez un espace de noms « MyBackgroundTasks » et une classe « BackgroundTask1 » qui contenait votre code de classe d’arrière-plan, la chaîne correspondant taskEntryPoint à « MyBackgroundTasks.BackgroundTasks.BackgroundTask1 ». Si votre tâche en arrière-plan s’exécute dans le même processus que votre application (c’est-à-dire qu’une tâche en arrière-plan in-process) taskEntryPoint ne doit pas être définie.

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 les inscriptions existantes

Vérifiez si la tâche est déjà inscrite. Il est important de vérifier cela, car si une tâche est inscrite plusieurs fois, elle s’exécute plusieurs fois chaque fois qu’elle est déclenchée ; cela peut utiliser l’excès de processeur et peut entraîner un comportement inattendu.

Vous pouvez rechercher des inscriptions existantes en interrogeant la propriété BackgroundTaskRegistration.AllTasks et en itérant sur le résultat. 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 pour que votre code puisse choisir un chemin différent à l’étape suivante.

Remarque : Utilisez des noms de tâches en arrière-plan uniques à votre application. Vérifiez que chaque tâche en arrière-plan a un nom unique.

Le code suivant inscrit une tâche en arrière-plan à l’aide de SystemTrigger que nous avons créé à la dernière étape :

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 retourner l’inscription existante)

Vérifiez si la tâche a été trouvée dans la liste des inscriptions de tâches en arrière-plan existantes. Si c’est le cas, retournez cette instance de la tâche.

Ensuite, inscrivez la tâche à l’aide d’un nouvel objet BackgroundTaskBuilder. Ce code doit vérifier si le paramètre de condition est null et, si ce n’est pas le cas, ajoutez la condition à l’objet d’inscription. Retournez l’BackgroundTaskRegistration retournée par la méthode BackgroundTaskBuilder.Register.

Notez que les paramètres d’inscription des tâches en arrière-plan sont validés au moment de l’inscription. Une erreur est retournée si l’un des paramètres d’inscription n’est pas valide. Assurez-vous que votre application gère correctement les scénarios où l’inscription des tâches en arrière-plan échoue. Si votre application dépend plutôt d’avoir un objet d’inscription valide après avoir tenté d’inscrire une tâche, il peut se bloquer. Notez que 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 taskEntryPoint paramètre.

L’exemple suivant retourne la tâche existante ou ajoute du code qui inscrit la tâche en arrière-plan (y compris la condition système facultative le cas échéant) :

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;
}

Terminer la fonction utilitaire d’inscription des tâches en arrière-plan

Cet exemple montre la fonction d’inscription de tâche en arrière-plan terminée. Cette fonction peut être utilisée pour inscrire la plupart des tâches en arrière-plan, à l’exception des tâches en arrière-plan réseau.

//
// 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;
}

Rubriques connexes

• Créer et inscrire une tâche en arrière-plan hors processus
• Créer et inscrire une tâche en arrière-plan in-process
• Déclarer des tâches en arrière-plan dans le manifeste de l’application
• Gérer une tâche en arrière-plan annulée
• Surveiller la progression et l’achèvement des tâches en arrière-plan
• Répondre aux événements système avec des tâches en arrière-plan
• Définir des conditions pour l’exécution d’une tâche en arrière-plan
• Mettre à jour une vignette dynamique à partir d’une tâche en arrière-plan
• Utiliser un déclencheur de maintenance
• Exécuter une tâche en arrière-plan en fonction d’un minuteur
• Recommandations relatives aux tâches en arrière-plan
• Déboguer une tâche en arrière-plan
• Comment déclencher des événements d’interruption, de reprise et d’arrière-plan dans des applications UWP (lors du débogage)