调试后台任务

2025-06-10

重要的应用程序接口（API）

Windows.ApplicationModel.Background

了解如何调试后台任务，包括 Windows 事件日志中的后台任务激活和调试跟踪。

调试进程内和进程外的后台任务

本主题主要介绍在独立于主机应用的独立进程中运行的后台任务。如果要调试进程内后台任务，则不会有单独的后台任务项目，并且可以在 OnBackgroundActivated（）（进程内后台代码运行的位置）上设置断点，并查看手动触发后台任务以调试后台任务代码的步骤 2，下面介绍了如何触发后台代码执行。

确保正确设置后台任务项目

本主题假设您已有一个包含需要调试的后台任务的现有应用。以下是特定于进程外后台任务的内容，不适用于进程内后台任务。

在 C# 和C++中，请确保主项目引用后台任务项目。如果此引用未到位，则后台任务不会包含在应用包中。
在 C# 和 C++ 中，确保后台任务项目的 输出类型 为“Windows 运行时组件”。
必须在包清单的入口点属性中声明后台类。

手动触发后台任务以调试后台任务代码

可以通过 Microsoft Visual Studio 手动触发后台任务。然后，您可以逐步执行代码并对其进行调试。

在 C# 中，将断点置于后台类的 Run 方法中（对于进程内后台任务，请将断点置于 App.OnBackgroundActivated（）中，并使用 System.Diagnostics编写调试输出。

在C++中，将断点置于后台类的 Run 函数中（对于进程内后台任务，请将断点置于 App.OnBackgroundActivated（）中，并使用 OutputDebugString编写调试输出。
在调试器中运行应用程序，然后使用 生命周期事件 工具栏触发后台任务。此下拉列表显示可由 Visual Studio 激活的后台任务的名称。

注释

默认情况下，Visual Studio 中不显示生命周期事件工具栏选项。若要显示这些选项，请右键单击 Visual Studio 中的当前工具栏，并确保启用 调试位置 选项。

为实现这一点，后台任务必须已经注册，并且必须仍然处于等待触发器的状态。例如，如果后台任务已注册了一个一次性 TimeTrigger 并且该触发器已触发，那么通过 Visual Studio 启动任务将不会产生任何效果。

注释

无法以这种方式激活使用以下触发器的后台任务：ApplicationTrigger、MediaProcessingTrigger、ControlChannelTrigger、PushNotificationTrigger，以及使用具有 SystemTrigger 的 SmsReceived 触发器类型的后台任务。
应用程序触发器 和 MediaProcessingTrigger 可以通过 trigger.RequestAsync()在代码中手动发出信号。
当后台任务激活时，调试器将附加到该任务并在 VS 中显示调试输出。

调试后台任务激活

注释

本部分特定于进程外运行的后台任务，不适用于进程内后台任务。

后台任务激活取决于以下三项：

后台任务类的名称和命名空间
包清单中指定的入口点属性
注册后台任务时由您的应用指定的入口点

使用 Visual Studio 记下后台任务的入口点：
- 在 C# 和C++中，记下后台任务项目中指定的后台任务类的名称和命名空间。
使用清单设计器检查后台任务是否已在包清单中正确声明：
- 在 C# 和C++中，入口点属性必须与后台任务命名空间匹配，后跟类名。例如：RuntimeComponent1.MyBackgroundTask。
- 还必须指定与任务一起使用的所有触发器类型。
- 除非使用 ControlChannelTrigger 或 PushNotificationTrigger，否则不可指定可执行文件。
仅限 Windows。若要查看 Windows 用于激活后台任务的入口点，请启用调试跟踪并使用 Windows 事件日志。

如果遵循此过程，并且事件日志显示后台任务的入口点或触发器错误，则应用未正确注册后台任务。有关此任务的帮助，请参阅注册后台任务。
1. 打开事件查看器，请转到“开始”屏幕并搜索 eventvwr.exe。
2. 转到事件查看器中的 应用程序和服务日志 ->Microsoft ->Windows ->BackgroundTaskInfrastructure。
3. 在操作窗格中，选择查看 ->显示分析和调试日志，以启用诊断日志功能。
4. 选择 诊断日志，然后单击 启用日志。
5. 现在，请尝试使用应用注册并再次激活后台任务。
6. 查看诊断日志以获取详细的错误信息。这将包括为后台任务注册的入口点。

用于后台任务调试信息的事件查看器

后台任务和 Visual Studio 包部署

如果使用 Visual Studio 部署了一个包含后台任务的应用程序，然后更新了清单设计器中指定的版本（主要和/或次要版本），那么在使用 Visual Studio 重新部署该应用时，应用的后台任务可能会停止。可按如下方式进行补救：

使用 Windows PowerShell 通过运行与包一起生成的脚本来部署更新的应用（而不是 Visual Studio）。
如果已使用 Visual Studio 部署应用，并且其后台任务现已停止，请重新启动或注销/登录，让应用的后台任务再次工作。
可以选择“始终重新安装我的包”调试选项，以避免在 C# 项目中执行此操作。
等到应用准备好进行最终部署以递增包版本（调试时不要更改它）。

注解

在重新注册后台任务之前，请确保您的应用程序检查现有的后台任务注册。同一背景任务的多次注册可能会导致意外结果，因为每次触发时，该任务可能会运行多次。
如果后台任务需要锁屏访问，请确保在尝试调试后台任务之前将应用置于锁屏界面上。有关为支持锁屏的应用指定清单选项的信息，请参阅声明应用程序清单中的后台任务。
后台任务注册参数在注册时会被验证。如果任何注册参数无效，则返回错误。确保应用程序能够有效处理后台任务注册失败的情况——如果在尝试注册任务后应用程序依赖于拥有有效的注册对象，那么它可能会崩溃。

有关使用 VS 调试后台任务的详细信息，请参阅如何在 UWP 应用中触发挂起、恢复和后台事件。

通过