Déboguer une tâche en arrière-planDebug a background task

API importantesImportant APIs

Découvrez comment déboguer une tâche en arrière-plan, notamment dans le cadre de son activation et du suivi de débogage dans le journal des événements Windows.Learn how to debug a background task, including background task activation and debug tracing in the Windows event log.

Déboguer des tâches en arrière-plan hors processus ou in-processDebugging out-of-process vs. in-process background tasks

Cette rubrique concerne principalement les tâches en arrière-plan qui s’exécutent dans un processus distinct que celui de l’application hôte.This topic primarily addresses background tasks that run in a separate process than the host app. Si vous déboguez une tâche en arrière-plan in-process, vous ne disposez pas d’un projet de tâche en arrière-plan distinct et pouvez définir un point d’arrêt sur OnBackgroundActivated () (où votre code en arrière-plan in-process s’exécute) et voir l’étape 2 dans déclencher manuellement des tâches en arrière-plan pour déboguer le code de tâcheIf you are debugging an in-process background task, then you won't have a separate background task project and can set a breakpoint on OnBackgroundActivated() (where your in-process background code runs) and see step 2 in Trigger background tasks manually to debug background task code, below, for instructions about how to trigger your background code to execute.

Vérifier que le projet de tâche en arrière-plan est configuré comme il se doitMake sure the background task project is set up correctly

Cette rubrique part du principe que vous disposez d’une application avec une tâche en arrière-plan à déboguer.This topic assumes that you already have an existing app with a background task to debug. La suite concerne les tâches en arrière-plan qui s’exécutent hors processus et non les tâches en arrière-plan in-process.The following is specific to background tasks that run out-of-process and does not apply to in-process background tasks.

  • En C# et C++, vérifiez que le projet principal fait référence au projet de tâche en arrière-plan.In C# and C++, make sure the main project references the background task project. En l’absence de cette référence, la tâche en arrière-plan n’est pas incluse dans le package d’application.If this reference is not in place, the background task won't be included in the app package.
  • En C# et C++, vérifiez que le Output type du projet de tâches en arrière-plan est « Composant Windows Runtime ».In C# and C++, make sure the Output type of the background task project is "Windows Runtime Component".
  • La classe d’arrière-plan doit être déclarée dans l’attribut de point d’entrée dans le manifeste du package.The background class must be declared in the entry point attribute in the package manifest.

Déclencher des tâches en arrière-plan manuellement pour déboguer le code de la tâche en arrière-planTrigger background tasks manually to debug background task code

Les tâches en arrière-plan peuvent être déclenchées manuellement par le biais de Microsoft Visual Studio.Background tasks can be triggered manually through Microsoft Visual Studio. Vous pouvez ensuite exécuter pas à pas le code et le déboguer.Then you can step through the code and debug it.

  1. En C#, insérez un point d’arrêt dans la méthode Run de la classe en arrière-plan (pour les tâches en arrière-plan in-process, placez le point d’arrêt dans App.OnBackgroundActivated()) et/ou écrivez la sortie de débogage à l’aide de System.Diagnostics.In C#, put a breakpoint in the Run method of the background class (for in-process background tasks put the breakpoint in App.OnBackgroundActivated()), and/or write debugging output by using System.Diagnostics.

    En C++, placez un point d’arrêt dans la fonction Run de la classe background (pour les tâches en arrière-plan in-process, placez le point d’arrêt dans App. OnBackgroundActivated ()) et/ou écrivez la sortie de débogage à l’aide de OutputDebugString.In C++, put a breakpoint in the Run function of the background class (for in-process background tasks put the breakpoint in App.OnBackgroundActivated()), and/or write debugging output by using OutputDebugString.

  2. Exécutez votre application dans le débogueur, puis déclenchez la tâche en arrière-plan à l’aide de la barre d’outils Événements de cycle de vie.Run your application in the debugger and then trigger the background task using the Lifecycle Events toolbar. Ce menu déroulant affiche le nom des tâches en arrière-plan qu’il est possible d’activer à l’aide de Visual Studio.This drop down shows the names of the background tasks that can be activated by Visual Studio.

    Notes

    Les options de la barre d’outils événements de cycle de vie ne sont pas affichées par défaut dans Visual Studio.The Lifecycle Events toolbar options are not shown by default in Visual Studio. Pour afficher ces options, cliquez avec le bouton droit sur la barre d’outils actuelle dans Visual Studio et assurez-vous que l’option emplacement de débogage est activée.To show these options, right-click on the current toolbar in Visual Studio and ensure the option Debug Location is enabled.

    Pour que cette opération fonctionne, la tâche en arrière-plan, doit déjà être inscrite et doit toujours attendre le déclencheur.For this to work, the background task must already be registered and it must still be waiting for the trigger. Par exemple, si une tâche en arrière-plan a été inscrite avec un TimeTrigger à déclenchement unique qui a déjà été déclenché, le lancement de la tâche via Visual Studio n’aura aucun effet.For example, if a background task was registered with a one-shot TimeTrigger and that trigger has already fired, launching the task through Visual Studio will have no effect.

    Notes

    Les tâches en arrière-plan utilisant les déclencheurs suivants ne peuvent pas être activées de cette manière : déclencheur d’application, déclencheur MediaProcessing, ControlChannelTrigger, PushNotificationTriggeret tâches en arrière-plan à l’aide d’un événement systemtrigger avec le type de déclencheur SmsReceived .Background tasks using the following triggers cannot be activated in this manner: Application trigger, MediaProcessing trigger, ControlChannelTrigger, PushNotificationTrigger, and background tasks using a SystemTrigger with the SmsReceived trigger type.
    Les déclencheurs ApplicationTrigger et MediaProcessingTrigger peuvent être déclarés manuellement dans le code avec trigger.RequestAsync().Application trigger and MediaProcessingTrigger can be signaled manually in code with trigger.RequestAsync().

    débogage des tâches en arrière-plan

  3. Lorsque la tâche en arrière-plan est activée, le débogueur s’y associe et affiche la sortie de débogage dans Visual Studio.When the background task activates, the debugger will attach to it and display debug output in VS.

Déboguer l’activation de la tâche en arrière-planDebug background task activation

Notes

Cette section concerne les tâches en arrière-plan qui s’exécutent hors processus et non les tâches en arrière-plan in-process.This section is specific to background tasks the run out-of-process and does not apply to in-process background tasks.

L’activation de la tâche en arrière-plan dépend de trois éléments :Background task activation depends on three things:

  • nom et espace de noms de la classe de tâche en arrière-plan ;The name and namespace of the background task class
  • attribut de point d’entrée spécifié dans le manifeste du package ;The entry point attribute specified in the package manifest
  • point d’entrée spécifié par votre application lors de l’inscription de la tâche en arrière-plan.The entry point specified by your app when registering the background task
  1. Utilisez Visual Studio pour noter le point d’entrée de la tâche en arrière-plan :Use Visual Studio to note the entry point of the background task:

    • En C# et C++, notez le nom et l’espace de noms de la classe de tâche en arrière-plan spécifiée dans le projet de tâche en arrière-plan.In C# and C++, note the name and namespace of the background task class specified in the background task project.
  2. Utilisez le concepteur du manifeste pour vérifier que la tâche en arrière-plan est correctement déclarée dans le manifeste du package :Use the manifest designer to check that the background task is correctly declared in the package manifest:

    • En C# et C++, l’attribut de point d’entrée doit correspondre à l’espace de noms de la tâche en arrière-plan suivi du nom de la classe.In C# and C++, the entry point attribute must match the background task namespace followed by the class name. Par exemple : RuntimeComponent1.MyBackgroundTask.For example: RuntimeComponent1.MyBackgroundTask.
    • Tous les types de déclencheurs utilisés avec la tâche doivent également être indiqués.All the trigger type(s) used with the task must also be specified.
    • L’exécutable ne doit pas être spécifié, sauf si vous utilisez ControlChannelTrigger ou PushNotificationTrigger.The executable MUST NOT be specified unless you are using the ControlChannelTrigger or PushNotificationTrigger.
  3. Windows uniquement.Windows only. Pour afficher le point d’entrée utilisé par Windows afin d’activer la tâche en arrière-plan, activez le suivi de débogage et utilisez le journal des événements Windows.To see the entry point used by Windows to activate the background task, enable debug tracing and use the Windows event log.

    Si vous suivez cette procédure et que le journal des événements indique un déclencheur ou point d’entrée incorrect pour la tâche en arrière-plan, votre application n’inscrit pas correctement la tâche en arrière-plan.If you follow this procedure and the event log shows the wrong entry point or trigger for the background task, your app is not registering the background task correctly. Pour obtenir de l’aide sur cette tâche, voir Inscrire une tâche en arrière-plan.For help with this task see Register a background task.

    1. Ouvrez l’Observateur d’événements en accédant à l’écran de démarrage et en recherchant eventvwr.exe.Open event viewer by going to the Start screen and searching for eventvwr.exe.
    2. Accédez à journaux des applications et des services - > Microsoft - > Windows - > BackgroundTaskInfrastructure dans l’observateur d’événements.Go to Application and Services Logs -> Microsoft -> Windows -> BackgroundTaskInfrastructure in the event viewer.
    3. Dans le volet Actions, sélectionnez Afficher - > afficher les journaux d’analyse et de débogage pour activer la journalisation des Diagnostics.In the actions pane, select View -> Show Analytic and Debug Logs to enable the diagnostic logging.
    4. Sélectionnez le journal de diagnostic, puis cliquez sur Activer le journal.Select the Diagnostic log and click Enable Log.
    5. Essayez à présent d’utiliser votre application pour inscrire et activer la tâche en arrière-plan une nouvelle fois.Now try using your app to register and activate the background task again.
    6. Consultez les journaux de diagnostic à la recherche d’informations détaillées sur l’erreur.View the diagnostic logs for detailed error information. Cela comprend le point d’entrée inscrit pour la tâche en arrière-plan.This will include the entry point registered for the background task.

informations de débogage des tâches en arrière-plan dans l’observateur d’événements

Tâches en arrière-plan et déploiement du package Visual StudioBackground tasks and Visual Studio package deployment

Si une application qui utilise des tâches en arrière-plan est déployée à l’aide de Visual Studio et que la version (major et/ou minor) spécifiée dans le concepteur de manifeste est ensuite mise à jour, le redéploiement de l’application avec Visual Studio peut entraîner le blocage des tâches en arrière-plan de l’application.If an app that uses background tasks is deployed using Visual Studio, and the version (major and/or minor) specified in Manifest Designer is then updated, subsequently re-deploying the app with Visual Studio may cause the app's background tasks to stall. Vous pouvez remédier à ce problème de la manière suivante.This can be remedied as follows:

  • Utilisez Windows PowerShell pour déployer l’application mise à jour (plutôt que Visual Studio). Pour cela, exécutez le script généré avec le package.Use Windows PowerShell to deploy the updated app (instead of Visual Studio) by running the script generated alongside the package.
  • Si vous avez déjà déployé l’application à l’aide de Visual Studio et que ses tâches en arrière-plan sont désormais bloquées, redémarrez ou déconnectez-vous pour que les tâches en arrière-plan de l’application fonctionnent à nouveau.If you already deployed the app using Visual Studio and its background tasks are now stalled, reboot or log off/log in to get the app's background tasks working again.
  • Vous pouvez sélectionner l’option de débogage « Toujours réinstaller mon package » pour éviter cela dans des projets C#.You can select the "Always re-install my package" debugging option to avoid this in C# projects.
  • Attendez que l’application soit prête pour le déploiement final afin d’incrémenter la version du package (ne la modifiez pas pendant le débogage).Wait until the app is ready for final deployment to increment the package version (don't change it while debugging).

NotesRemarks

  • Assurez-vous que votre application vérifie la présence d’inscriptions de tâches en arrière-plan existantes avant d’inscrire de nouveau la tâche en arrière-plan.Make sure your app checks for existing background task registrations before registering the background task again. Plusieurs inscriptions de la même tâche en arrière-plan peuvent entraîner des résultats inattendus si vous exécutez plusieurs fois la tâche en arrière-plan à chacun de ses déclenchements.Multiple registrations of the same background task can cause unexpected results by running the background task more than once each time it is triggered.
  • Si la tâche en arrière-plan requiert un accès à l’écran de verrouillage, veillez à placer l’application sur l’écran de verrouillage avant d’essayer de déboguer la tâche en arrière-plan.If the background task requires lock screen access make sure to put the app on the lock screen before trying to debug the background task. Pour plus d’informations sur la spécification des options de manifeste pour les applications compatibles avec l’écran de verrouillage, consultez Déclarer des tâches en arrière-plan dans le manifeste de l’application.For info on specifying manifest options for lock screen-capable apps, see Declare background tasks in the application manifest.
  • 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.

Pour plus d’informations sur l’utilisation de VS pour déboguer une tâche en arrière-plan , consultez Comment déclencher des événements de suspension, de reprise et d’arrière-plan dans les applications UWP.For more info on using VS to debug a background task see How to trigger suspend, resume, and background events in UWP apps.