Отладка фоновой задачиDebug a background task

Важные APIImportant APIs

Узнайте, как отладить фоновую задачу, выполнив в том числе активацию фоновой задачи и трассировку отладки в журнале событий Windows.Learn how to debug a background task, including background task activation and debug tracing in the Windows event log.

Сравнение отладки фоновых задач, выполняемых вне процесса, с фоновыми задачами внутри процессаDebugging out-of-process vs. in-process background tasks

В этом разделе в основном рассматриваются фоновые задачи, которые выполняются в отдельном процессе, отличном от процесса основного приложения.This topic primarily addresses background tasks that run in a separate process than the host app. Если выполняется отладка фоновой задачи, выполняемой внутри процесса, отдельный проект фоновой задачи отсутствует, и можно задать точку останова в OnBackgroundActivated (где выполняется ваш фоновый код внутри процесса); затем см. шаг 2 в разделе Ручная активация фоновых задач для отладки их кода ниже, в котором приведены инструкции по запуску выполнения фонового кода.If 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.

Правильная настройка параметров проекта фоновой задачиMake sure the background task project is set up correctly

В этой статье предполагается, что у вас уже есть приложение с фоновой задачей, которую необходимо отладить.This topic assumes that you already have an existing app with a background task to debug. Приведенная ниже информация относится к фоновым задачам, которые выполняются вне процесса; она не касается фоновых задач, выполняющихся внутри процесса.The following is specific to background tasks that run out-of-process and does not apply to in-process background tasks.

  • Для приложений на языках C# и C++ основной проект должен ссылаться на проект фоновой задачи.In C# and C++, make sure the main project references the background task project. Если такой ссылки нет, то фоновая задача не будет включена в пакет приложения.If this reference is not in place, the background task won't be included in the app package.
  • В коде на языке C# или C++ параметр Тип вывода проекта фоновой задачи должен иметь значение "Компонент среды выполнения Windows".In C# and C++, make sure the Output type of the background task project is "Windows Runtime Component".
  • Фоновый класс необходимо объявить в атрибуте точки входа в манифесте пакета.The background class must be declared in the entry point attribute in the package manifest.

Ручная активация фоновых задач для отладки их кодаTrigger background tasks manually to debug background task code

Фоновые задачи могут быть запущены вручную через Microsoft Visual Studio.Background tasks can be triggered manually through Microsoft Visual Studio. После этого можно по шагам выполнять код и его отладку.Then you can step through the code and debug it.

  1. В C# поместите точку останова в метод Run фонового класса (для фоновых задач внутри процесса установите точки останова в App.OnBackgroundActivated()) и/или напишите отладочный вывод с помощью 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.

    В C++ поместите точку останова в функцию Run фонового класса (для фоновых задач внутри процесса установите точки останова в App.OnBackgroundActivated()) и/или напишите отладочный вывод с помощью 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. Запустите приложение в отладчике, затем активируйте фоновую задачу с помощью панели инструментов События жизненного цикла.Run your application in the debugger and then trigger the background task using the Lifecycle Events toolbar. В этом раскрывающемся меню отображаются имена фоновых задач, которые можно активировать с помощью Visual Studio.This drop down shows the names of the background tasks that can be activated by Visual Studio.

    Примечание

    Параметры панели инструментов события жизненного цикла по умолчанию не отображаются в Visual Studio.The Lifecycle Events toolbar options are not shown by default in Visual Studio. Чтобы отобразить эти параметры, щелкните правой кнопкой мыши текущую панель инструментов в Visual Studio и убедитесь, что параметр Расположение отладки включен.To show these options, right-click on the current toolbar in Visual Studio and ensure the option Debug Location is enabled.

    Для того чтобы это работало, фоновая задача должна быть уже зарегистрирована и ожидать запуска.For this to work, the background task must already be registered and it must still be waiting for the trigger. Например, если фоновая задача была зарегистрирована с одноразовым триггером времени TimeTrigger, который уже был активирован, запуск задачи через Visual Studio не сработает.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.

    Примечание

    Таким способом невозможно запустить фоновые задачи, использующие следующие триггеры: ApplicationTrigger, MediaProcessingTrigger, ControlChannelTrigger, PushNotificationTrigger и фоновые задачи, использующие SystemTrigger с типом триггера 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.
    ApplicationTrigger и MediaProcessingTrigger можно установить в коде вручную с помощью trigger.RequestAsync().Application trigger and MediaProcessingTrigger can be signaled manually in code with trigger.RequestAsync().

    отладка фоновых задач

  3. При активации фоновой задачи отладчик подключается к ней и отображает отладочный вывод в Visual Studio.When the background task activates, the debugger will attach to it and display debug output in VS.

Отладка активации фоновой задачиDebug background task activation

Примечание

Этот раздел относится к фоновым задачам, которые выполняются вне процесса; он не касается фоновых задач, выполняющихся внутри процесса.This section is specific to background tasks the run out-of-process and does not apply to in-process background tasks.

Активация фоновой задачи зависит от трех условий:Background task activation depends on three things:

  • Имя и пространство имен класса фоновой задачи.The name and namespace of the background task class
  • Атрибут точки входа, указанный в манифесте пакета.The entry point attribute specified in the package manifest
  • Точка входа, заданная приложением при регистрации фоновой задачи.The entry point specified by your app when registering the background task
  1. Используя Visual Studio, определите точку входа фоновой задачи:Use Visual Studio to note the entry point of the background task:

    • В коде на языке C# или C++ запомните имя и пространство имен класса фоновой задачи, указанные в проекте фоновой задачи.In C# and C++, note the name and namespace of the background task class specified in the background task project.
  2. С помощью конструктора манифеста проверьте, правильно ли объявлена фоновая задача в манифесте пакета.Use the manifest designer to check that the background task is correctly declared in the package manifest:

    • В коде на языке C# или C++ атрибут точки входа должен соответствовать пространству имен фоновой задачи, за которым следует имя класса.In C# and C++, the entry point attribute must match the background task namespace followed by the class name. Например: RuntimeComponent1.MyBackgroundTask.For example: RuntimeComponent1.MyBackgroundTask.
    • Кроме того, необходимо указать все типы триггеров, которые использует задача.All the trigger type(s) used with the task must also be specified.
    • Исполняемый файл НЕ СЛЕДУЕТ указывать, если только вы не используете ControlChannelTrigger или PushNotificationTrigger.The executable MUST NOT be specified unless you are using the ControlChannelTrigger or PushNotificationTrigger.
  3. Только Windows.Windows only. Чтобы увидеть точку входа, используемую Windows для активации фоновой задачи, включите трассировку отладки и используйте журнал событий Windows.To see the entry point used by Windows to activate the background task, enable debug tracing and use the Windows event log.

    Если после выполнения этой процедуры в журнале событий отображается неправильная точка входа или триггер фоновой задачи, это означает, что приложение неправильно регистрирует фоновую задачу.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. Разобраться с такой задачей поможет статья Регистрация фоновой задачи.For help with this task see Register a background task.

    1. Перейдите на начальный экран и откройте просмотр событий (для этого найдите и запустите файл eventvwr.exe).Open event viewer by going to the Start screen and searching for eventvwr.exe.
    2. Перейдите в раздел журналы приложений и служб - > Microsoft - > Windows - > баккграундтаскинфраструктуре в средстве просмотра событий.Go to Application and Services Logs -> Microsoft -> Windows -> BackgroundTaskInfrastructure in the event viewer.
    3. На панели действия выберите вид - > Показать журналы аналитики и отладки , чтобы включить ведение журнала диагностики.In the actions pane, select View -> Show Analytic and Debug Logs to enable the diagnostic logging.
    4. Выберите Журнал диагностики и щелкните Включить журнал.Select the Diagnostic log and click Enable Log.
    5. Теперь попробуйте еще раз использовать ваше приложение для регистрации и активации фоновой задачи.Now try using your app to register and activate the background task again.
    6. Просмотрите в журналах диагностики подробную информацию об ошибке.View the diagnostic logs for detailed error information. Эта информация будет содержать точку входа, зарегистрированную для фоновой задачи.This will include the entry point registered for the background task.

Просмотр событий для информации об отладке фоновых задач

Фоновые задачи и развертывание пакета Visual StudioBackground tasks and Visual Studio package deployment

Если приложение, использующее фоновые задачи, развертывается с помощью Visual Studio, а версия (основная и/или младшая), указанная в конструкторе манифестов, обновляется, впоследствии повторное развертывание приложения с помощью Visual Studio может привести к зависанию фоновых задач приложения.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. Эту проблему можно решить следующим образом:This can be remedied as follows:

  • Используйте Windows PowerShell для развертывания обновленного приложения (вместо Visual Studio), запустив сценарий, созданный вместе с пакетом.Use Windows PowerShell to deploy the updated app (instead of Visual Studio) by running the script generated alongside the package.
  • Если вы уже развернули приложение с помощью Visual Studio, и его фоновые задачи теперь остановлены, перезагрузите или выйдите из системы и войдите в систему, чтобы получить возможность повторной работы фоновых задач приложения.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.
  • Вы можете выбрать параметр отладки "Всегда переустанавливать мой пакет", чтобы избежать этого в проектах C#.You can select the "Always re-install my package" debugging option to avoid this in C# projects.
  • Дождитесь готовности приложения к окончательному развертыванию, чтобы увеличить версию пакета (не изменяйте его во время отладки).Wait until the app is ready for final deployment to increment the package version (don't change it while debugging).

RemarksRemarks

  • Убедитесь, что перед повторной регистрацией фоновой задачи приложение проверяет существующие регистрации фоновых задач.Make sure your app checks for existing background task registrations before registering the background task again. Многократная регистрация одной и той же фоновой задачи может привести к неожиданным результатам, так как фоновая задача будет запускаться каждый раз при ее активации.Multiple registrations of the same background task can cause unexpected results by running the background task more than once each time it is triggered.
  • Если фоновой задаче требуется доступ к экрану блокировки, то перед выполнением ее отладки необходимо, чтобы приложение было размещено на экране блокировки.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. Сведения о том, как указывать параметры манифеста для приложений с возможностью размещения на экране блокировки, см. в статье Объявление фоновых задач в манифесте приложения.For info on specifying manifest options for lock screen-capable apps, see Declare background tasks in the application manifest.
  • Параметры регистрации фоновых задач проверяются во время регистрации.Background task registration parameters are validated at the time of registration. Если какие-либо из параметров регистрации недопустимы, возвращается ошибка.An error is returned if any of the registration parameters are invalid. Убедитесь, что ваше приложение корректно обрабатывает сценарии, в которых регистрация фоновой задачи завершается ошибкой. Если работа вашего приложения зависит от наличия допустимого объекта регистрации после попытки регистрации задачи, то оно может дать сбой.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.

Дополнительные сведения об использовании VS для отладки фоновой задачи см. в статье как активировать события приостановки, возобновления и фоновых событий в приложениях UWP.For more info on using VS to debug a background task see How to trigger suspend, resume, and background events in UWP apps.