DbgShell

一个用于Windows调试器引擎的PowerShell前端。

准备好用Tab键快速导航了吗？快速入门请参阅入门指南。

免责声明

1. 本项目并非由Windows调试器团队制作、认可或监控。虽然调试器团队欢迎对其API和前端（windbg， kd等）的反馈，但他们与本项目无关。请不要针对本项目向调试器团队提交错误报告或反馈。

2. 这不是一个受资助的项目：它没有官方分配的资源，仅由志愿者完成。除非您愿意完全自行支持该项目，否则请不要将任何生产依赖置于该项目之上。欢迎提交Issue和Pull Request，但请注意，由于志愿者资源有限，您的提交可能需要一段时间才能得到处理。

3. 这是一个实验性项目：尚未完全成熟，您应预期会经常发生重大变更。

以上免责声明的推论：我建议不要将DbgShell连接到高价值的实时目标。

二进制文件

https://aka.ms/dbgshell-latest

动机

您是否曾尝试在调试器中自动化任何操作？（cdb/ntsd/kd/windbg）结果如何？

DbgShell的主要推动力是在调试器中实现自动化简直太难了。当然，目前有一些辅助调试器自动化的工具。但在我看来，它们未能满足人们的需求。

• 使用内置脚本语言是晦涩的、有限的、难以正确使用，并且难以获得帮助。
• 编写一个完整的调试器扩展DLL非常强大，但需要巨大的投入——对于在调试随机现实问题时快速解决“一次性”问题来说，成本太高了。尽管成本高昂，但存在大量调试器扩展。我认为不应该有这么多；我认为它们之所以这么多，唯一的原因是缺乏可行的替代方案。
• 现有的提供更好接口的尝试（例如PowerDbg）基于“抓取”和文本解析，这极大地限制了（更不用说在理念上令人恼火），因此无法实现真正更好接口的承诺（至多只是略有改进）。
• 现有的提供更简单编写调试器扩展的尝试仅仅是权宜之计，解决了开发调试器扩展的痛苦；它们并未真正解决更大的问题。（例如，两个主要缺点是：它们仍然过于底层（必须处理dbgeng COM API），并且没有REPL）
• 调试器团队最近引入了Javascript脚本。JavaScript比旧的windbg脚本语言要好得多（定义也更明确），但我认为PowerShell有一些优势，其中最大的优势是没有人真正使用JavaScript shell——PowerShell作为组合的shell和脚本语言要好得多。

DbgShell项目的目标是将基于对象的PowerShell世界的优点带入调试世界。 当你执行'dt'来转储一个'对象'时，你应该得到一个实际的对象。脚本编写应该像编写PowerShell脚本一样简单。

DbgShell项目为dbgeng.dll提供了一个PowerShell前端，包括：

• 一个托管“对象模型”（如果你愿意，可以从C#使用），比dbgeng COM API更高级，
• 一个PowerShell“导航提供程序”，将调试目标的各种方面暴露为分层命名空间（因此你可以“cd”到某个线程，输入“dir”查看堆栈，“cd”进入某个帧，再次执行“dir”查看局部变量/寄存器等），
• 用于操作目标的cmdlet，
• 一个自定义的PowerShell主机，可以更好地控制调试器CLI体验，并提供标准powershell.exe主机中没有的功能（即支持使用ANSI转义码进行文本着色（遵循ISO/IEC 6429））

自定义主机仍然是一个命令行（基于conhost.exe）程序（类似于ntsd/cdb/kd），但可以从windbg中调用（!DbgShell）。

除了使自动化变得更加容易和强大之外，它还将解决其他问题，例如对于不需要经常使用调试器的人来说易用性。（我听到的一个抱怨是：“当我最终需要使用windbg时，我所有时间都花在.CHM上”）

另一方面，对于经验丰富的windbg用户，另一个目标是使过渡尽可能无缝。因此，例如，命名空间提供程序并不是访问数据的唯一方式；你仍然可以使用传统的命令，如“~3 s”、“k”等。

你所说的“自动化”和“脚本”是什么意思？

我指的不仅仅是打开文本编辑器编写一些大型脚本来完成复杂操作——我也指的是在命令行上快速编写相对简单的内容。有很多情况下，你需要一些逻辑，但又不至于大到或可重复使用到需要保存它。应该很容易地编写出像“在CreateFile上设置断点，如果打开的文件在用户的桌面上并且函数Blah在堆栈上”这样的“一行代码”。

为什么选择PowerShell？

让我说清楚：我花了大约4年的时间才“接受”PowerShell。我觉得它有尖锐的边缘，有些方面就是很困难，并且在设计和实现上都有很多缺陷。有时它真的让我恼火。然而，PowerShell的好处是令人信服的，并且已经说服我它是这个项目的最佳选择：

• 它既是脚本环境又是CLI环境。它必须同时承担这两个角色导致了一些负面影响，比如学习曲线更陡峭，但最终它非常方便，因为你既可以在命令行REPL中快速完成操作，也可以编写功能完整、健壮的脚本。
• 它具有很强的可发现性——像Get-Command、Tab自动补全、像文件系统一样暴露分层数据的能力、提供和合成帮助的功能都非常好。
• Tab自动补全。我知道我在前一点中提到了，但它足够棒，值得单独列出。
• 对象管道：PowerShell管道的面向对象性质比过去基于字符串解析的脚本要强大和易用得多，这甚至不好笑。想象一下执行“dt”来“转储”一个“对象”，并实际得到一个对象。DbgShell做到了这一点。
• 人们熟悉它：我估计熟悉PowerShell和/或C#的人数至少比熟悉windbg脚本技术的人数高出几个数量级。这意味着更多的人将能够轻松地“上手”基于PowerShell的调试器；这也意味着当人们需要帮助时，潜在帮助者的池子更大（至少对于脚本相关的问题而言）。
• PowerShell仍然是一个通用shell：使用DbgShell时，你不仅可以访问调试器命令，还可以“cd”到文件系统、注册表、AD等；你可以执行Send-MailMessage、Get-WmiObject、Invoke-WebRequest、Invoke-RestMethod，运行任意程序等。

当前状态

DbgShell长期处于“原型模式”。我花了很多时间来弄清楚某些事情可以或应该怎么做，但未必“完成”所有事情。当前代码中有大量的TODO。因此，尽管它已经开始变得真正有用，但该项目仍然相当初级。然而，它确实足以展示出应有的样子。

以下是一些截图。重要的是要注意，你看到的任何内容都不是dbgeng的文本输出。尽管输出中的某些内容看起来很熟悉，但那只是因为我使用了PowerShell的格式化和输出功能来定制某些对象的显示方式——你看到的所有输出实际上都对应着真正的、完整的.NET对象。例如，那些ModLoad消息每个都对应一个MS.Dbg.ModuleLoadedEventArgs对象，它有比发送到Out-Default时显示的更多的属性。完全没有对来自dbgeng的任何内容进行字符串解析。（嗯……几乎。我在一些没有其他方法获取信息的地方做了一些妥协。例如，反汇编内容，或者解析adjustor thunk函数的符号名称以查找偏移量。）

这是一个“hello world”场景：附加到一个cmd.exe实例。我首先使用PowerShell内置命令Start-Process，然后将输出通过管道传递给DbgShell命令Connect-Process，然后在命名空间中探索：

在这里，我附加到了一个测试程序，查看了堆栈，切换到了一个特定的堆栈帧，转储了局部变量，检查了一个局部std::map的值，并检查了一个局部枚举值的类型信息。注意枚举值的显示：DbgShell不仅能够处理单个枚举项的名称查找，还能处理多个枚举项通过OR组合的情况。从截图中看不出来，但所有这些都有Tab补全。

显著特性

• 颜色：支持使用ANSI转义码进行文本着色（遵循ISO/IEC 6429）
• 自定义格式化引擎：不喜欢.ps1xml的东西？我也不喜欢。除了标准的表格、列表和自定义视图外，你还可以定义“单行”视图，这对于自定义符号值显示非常方便。
• 自定义符号值转换：对于大多数变量，默认转换和显示已经足够。但有时，你可能希望调试器为你多做一点工作。符号值转换功能允许将例如STL集合对象转换为更容易处理的.NET集合对象。
• 派生类型检测：当你的变量是IFoo，但实际对象是FooImpl时。
• 丰富的类型信息：为你的编程乐趣而暴露。
• 问： 它能在WinDbg中使用吗？我只使用WinDbg。答： 可以——加载DbgShellExt.dll扩展DLL，然后运行“!dbgshell”打开一个DbgShell控制台。

当前缺陷

• 目前最大的缺陷是不支持内核模式良好（如果你已经在正确的上下文中，可以显示值，但无法在DbgShell内更改上下文，并且命名空间没有连接好）。
• 虽然你可以以通常的方式加载和执行传统的调试器扩展，但仍然缺少许多windbg命令。
• 不支持远程：dbgeng API支持连接到远程调试器。不幸的是，dbgeng API暴露的符号和类型信息严重不足，无法满足DbgShell的需求，因此DbgShell使用dbghelp API。不幸的是，没有所谓的远程dbghelp。我们需要与调试器团队合作来解决这个问题。

许可

根据MIT许可证授权。

贡献

本项目欢迎贡献和建议。大多数贡献要求您同意一份贡献者许可协议（CLA），声明您有权并确实授予我们使用您的贡献的权利。详情请访问 https://cla.microsoft.com。

当您提交pull request时，一个CLA-bot将自动确定您是否需要提供CLA，并适当装饰PR（例如，标签、评论）。只需按照bot提供的说明操作。您只需在使用我们CLA的所有仓库中执行一次此操作。

有关贡献项目的更多信息，请参阅贡献。

行为准则

本项目采用了Microsoft开源行为准则。

更多信息请参阅行为准则常见问题或联系[email protected]提出任何其他问题或意见。

其他主题

• DbgShell入门指南

• 颜色

• 自定义格式化引擎

• 自定义符号值转换

• 派生类型检测

• 丰富的类型信息

• 在DbgShell上开发

• DbgEngWrapper

您可以在这里找到简短的（3分钟）视频介绍：https://youtu.be/ynbg2zZ1Igc