在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

microsoft/PowerToys

菜单

调试工具

相关源文件

本文档记录了 PowerToys 项目中可用于开发者诊断和解决问题的各种调试工具和机制。这些工具可帮助收集诊断信息、分析代码行为以及生成报告以进行故障排除。有关从源代码构建 PowerToys 的信息，请参阅 从源代码构建。

调试设施概述

PowerToys 提供了多种设施来帮助进行调试和诊断问题

  1. 构建配置 - 具有不同优化级别的 Debug 和 Release 构建
  2. BugReportTool - 生成全面的诊断报告以进行故障排除
  3. 日志系统 - 捕获应用程序中的运行时事件和错误
  4. 代码分析工具 - 静态分析规则和检查
  5. 监视器诊断工具 - 用于显示相关问题的专用实用程序

调试工作流程

来源

构建配置

PowerToys 支持多种构建配置，以方便调试

配置平台描述
调试x64禁用优化，包含调试信息
调试ARM64禁用优化，包含调试信息
发布x64优化速度，调试更困难
发布ARM64优化速度，调试更困难

Debug 配置包含对调试有用的额外信息

  • 为 PDB 文件生成调试信息
  • 启用运行时检查
  • 禁用优化
  • 预处理器定义包括 _DEBUG

这些配置定义在项目属性文件中，特别是在 Cpp.Build.props 中。

来源

代码分析

PowerToys 使用 Microsoft 本机代码分析和 C++ Core Guidelines 规则进行静态代码分析。这可以在潜在问题演变成运行时 bug 之前进行早期检测。

规则集配置在 CppRuleSet.ruleset 中，该文件启用特定规则并禁用其他规则。代码分析在构建时和 PR CI 中运行（但在发布 CI 中不运行）。

代码分析的关键设置

来源

BugReportTool

BugReportTool 是一个命令行实用程序，用于收集有关 PowerToys 安装的全面诊断信息，以协助进行故障排除。它可以在安装目录中找到 PowerToys.BugReportTool.exe。

用途

该工具可以通过一个可选参数运行，指定在哪里保存生成的 ZIP 文件

PowerToys.BugReportTool.exe [output_zip_path]

如果未提供路径，则默认将 ZIP 文件保存在桌面。

系统架构

数据收集组件

BugReportTool 收集以下信息

  1. PowerToys 设置 - 复制整个 PowerToys 设置目录（已对私有数据进行审核）
  2. 日志文件 - 收集来自 %LOCALAPPDATA%\Microsoft\PowerToys\logs 的日志
  3. 安装详情 - 报告已安装的文件、版本和校验和
  4. Windows 版本 - 有关 Windows 版本的信息
  5. 注册表信息 - 与 PowerToys 相关的注册表项
  6. 监视器信息 - 显示配置详细信息
  7. 事件日志 - PowerToys 相关的 Windows 事件查看器条目
  8. 组策略 - 影响 PowerToys 的已配置 GPO 设置
  9. .NET 运行时信息 - 已安装的 .NET 运行时版本

隐私保护

BugReportTool 具有内置功能，可以在创建报告之前审核敏感信息

  • 包含设置文件中个人信息的路径
  • 安全密钥和个人身份识别字符串
  • 缓存文件和用户历史记录

这由 HideUserPrivateInfo 函数处理，该函数

  • 将 JSON 文件中的敏感数据替换为 <private_data> 占位符
  • 删除可能包含私有数据的特定文件

来源

日志系统

PowerToys 实现了一个全面的日志系统，用于捕获运行时事件、错误和诊断信息。日志主要在 Logger 类中实现。

代码中的使用

日志记录可以按不同级别进行

日志存储在 %LOCALAPPDATA%\Microsoft\PowerToys\logs\ 中，并且包含在 BugReportTool 生成的错误报告中。

日志分析

日志文件可以进行分析以了解

  • 启动顺序和初始化问题
  • 模块加载问题
  • 运行时错误和异常
  • 性能瓶颈
  • 用户交互顺序

来源

事件分析

Windows 事件查看器日志提供了有关 PowerToys 崩溃和其他系统级事件的关键信息。BugReportTool 包含提取相关事件的功能。

BugReportTool 中的 EventViewer 类收集来自 Windows 事件日志系统、与 PowerToys 进程相关的应用程序日志。它查询过去 10 天的事件，并将其格式化为 XML 以便分析。

来源

注册表分析

PowerToys 因各种功能与 Windows 注册表进行交互，调试通常需要检查注册表状态。BugReportTool 包含全面的注册表分析功能。

该工具收集与 PowerToys 相关的特定注册表项的信息，包括：

  • Shell 扩展注册
  • 与 Windows Explorer 的集成点
  • 文件关联
  • 应用程序兼容性设置

这由 ReportRegistry 和 ReportCompatibilityTab 函数处理，它们查询注册表并将结果格式化以供分析。

来源

监视器诊断

由于许多 PowerToys 实用程序都与显示器和屏幕交互，因此调试工具包中包含专用的监视器诊断功能。

MonitorReportTool

此工具收集有关连接显示器的详细信息

  • 物理监视器信息（制造商、型号、序列号）
  • 显示配置和拓扑
  • 活动显示模式和功能
  • WMI 监视器识别数据
  • 虚拟桌面配置

BugReportTool 中的监视器信息

BugReportTool 还通过 ReportMonitorInfo 函数包含更轻量级的监视器诊断版本，该函数收集

  • 基本显示枚举
  • 活动监视器计数
  • 显示设备属性
  • 监视器驱动程序信息

来源

更新系统调试

PowerToys 包含一个可能引起问题的更新系统。存在专门的调试机制用于诊断与更新相关的问题。

更新系统基于状态机，根据版本检查、下载状态和安装进度在不同状态之间转换。调试此系统通常涉及检查日志以及使用 BugReportTool 收集状态信息。

更新系统调试的关键组件

  • UpdateState 类中的更新状态跟踪
  • 通过 IsMeteredConnection() 进行网络连接检查
  • 版本比较逻辑
  • 用于更新事件的通知系统

来源

通知系统调试

PowerToys 使用吐司通知系统与用户进行通信。调试通知问题需要理解通知架构。

notifications 命名空间提供了显示、更新和删除吐司通知的功能。在调试通知问题时，可以检查这些组件

  1. 吐司 XML 生成 - 系统为 Windows 通知系统构建 XML
  2. 通知激活 - 用户与通知交互时的回调处理
  3. 进度更新 - 用于更新进行中通知进度条的机制

来源

模块特定调试

每个 PowerToys 模块可能有特定的调试技术。例如，快捷指南模块为叠加窗口和缩略图渲染提供了专门的调试。

快捷指南调试

快捷指南模块使用 D2DOverlayWindow 进行渲染。调试此模块时，请关注

  1. 缩略图渲染 - 如何捕获和显示窗口缩略图
  2. 动画计时 - 淡入/淡出动画的进度
  3. 窗口状态检测 - 确定窗口是否最大化、最小化或贴靠的逻辑
  4. 事件日志记录 - 跟踪覆盖层可见持续时间

来源

用于调试的执行命令

有几个可执行的工具可用于调试 PowerToys

工具用途描述
PowerToys.BugReportTool.exePowerToys.BugReportTool.exe [output_path]收集全面的诊断信息
PowerToys.Update.exe由运行器内部使用处理更新安装过程
PowerToys.exe -debug_trace以启用调试跟踪的方式运行启用更详细的日志记录

来源

使用 exec_and_read_output 进行 CLI 调试

PowerToys 包括一个实用函数 exec_and_read_output，它允许捕获命令行工具的输出以用于调试目的。BugReportTool 在此函数用于收集已安装的 .NET 运行时信息。

此函数可用于

  • 捕获系统实用程序的输出
  • 测试命令行工具
  • 诊断环境特定的问题

来源

结论

PowerToys 提供了一套强大的调试工具，可帮助开发人员诊断和修复整个应用程序中的问题。从全面的 BugReportTool 到用于监视显示器和分析注册表状态的专用实用程序，这些工具构成了一个完整的调试生态系统。

遇到 PowerToys 问题时，请从适当的调试配置开始，使用日志系统跟踪问题，并在必要时使用 BugReportTool 收集诊断信息。对于特定于模块的问题，请参考特定于该模块的专用调试技术。