DbgShell – PowerShell Front-End for Windows Debugger Engine

There are facilities today to assist in automating the debugger, of course. But in my opinion they are not meeting people’s needs.

• Using the built-in scripting language is arcane, limited, difficult to get right, and difficult to get help with.
• DScript is kind of neat, but virtually unknown, and it lacks a REPL, and it’s too low-level.
• Writing a full-blown debugger extension DLL is very powerful, but it’s a significant investment—way too expensive for solving quick, “one-off” problems as you debug random, real-world problems. Despite the cost, there are a large number of debugger extensions in existence. I think there should not be nearly so many; I think the only reason there are so many is because there aren’t viable alternatives.
• Existing attempts at providing a better interface (such as PowerDbg) are based on “scraping” and text parsing, which is hugely limiting (not to mention idealogically annoying) and thus are not able to fulfill the promise of a truly better interface (they are only marginally better, at best).
• Existing attempts to provide an easier way to write a debugger extension are merely a stop-gap addressing the pain of developing a debugger extension; they don’t really solve the larger problem. (for instance, two major shortcomings are: they are still too low-level (you have to deal with the dbgeng COM API), and there’s no REPL)
• The debugger team has recently introduce Javascript scripting. Javascript is a much better (and more well-defined) language than the old windbg scripting language, but I think that PowerShell has some advantages, the largest of which is that nobody really uses a Javascript shell–PowerShell is much better as a combined shell and scripting language.

   The goal of the DbgShell project is to bring the goodness of the object-based PowerShell world to the debugging world. When you do ‘dt’ to dump an ‘object’, you should get an actual object. Scripting should be as easy as writing a PowerShell script.

The DbgShell project provides a PowerShell front-end for dbgeng.dll, including:

• a managed “object model” (usable from C# if you wished), which is higher-level than the dbgeng COM API,
• a PowerShell “navigation provider”, which exposes aspects of a debugging target as a hierarchical namespace (so you can “cd” to a particular thread, type “dir” to see the stack, “cd” into a frame, do another “dir” to see locals/registers/etc.),
• cmdlets for manipulating the target,
• a custom PowerShell host which allows better control of the debugger CLI experience, as well as providing features not available in the standard powershell.exe host (namely, support for text colorization using ANSI escape codes (a la ISO/IEC 6429))

The custom host is still a command-line (conhost.exe-based) program (analogous to ntsd/cdb/kd), but it can be invoked from windbg (!DbgShell).

In addition to making automation much easier and more powerful, it will address other concerns as well, such as ease of use for people who don’t have to use the debuggers so often. (one complaint I’ve heard is that “when I end up needing to use windbg, I spend all my time in the .CHM”)

For seasoned windbg users, on the other hand, another goal is to make the transition as seamless as possible. So, for instance, the namespace provider is not the only way to access data; you can still use traditional commands like “~3 s“, “k“, etc.

Why PowerShell?

Let me be clear: it took me approximately 4 years to “warm up” to PowerShell. I feel it has sharp edges, aspects that are just plain difficult, and plenty of bugs, both in design and implementation. Sometimes it really irritates me. However, the benefits of PowerShell are compelling, and have convinced me that it’s the best thing to use for this project:

• It is both a scripting environment and a CLI environment. The fact that it has to do both leads to some negative things like a steeper learning curve, but in the end it is extremely handy, because you want to be able to both do stuff quickly in a command-line REPL, as well as write full-featured, robust scripts.
• It is very discoverable—things like Get-Command, tab completion, the ability to expose hierarchical data like a filesystem, the facilities for providing and synthesizing help, are very good.
• Tab completion. I know I mentioned it in the previous bullet, but it’s awesome enough to get its very own bullet.
• The object pipeline: the object-oriented nature of the PowerShell pipeline is so much more powerful and easy to use than the bad old days of string-parsing-based scripting that it’s not even funny. Imagine doing “dt” to “dump” an “object”, and actually getting an object. DbgShell does that.
• People know it: I estimate that the number of people who know PowerShell and/or C# is at least a handful of orders of magnitude larger than the people who know windbg scripting techniques. That means more people will be able to easily “pick up” a PowerShell-based debugger; and it also means that when people need help, the pool of potential helpers is much larger (for scripting-related issues, anyway).
• PowerShell is still a general-purpose shell: when using DbgShell, you have access to not just debugger commands, but you can “cd” over to the filesystem, registry, AD, etc.; you can execute Send-MailMessage, Get-WmiObject, Invoke-WebRequest, Invoke-RestMethod, run arbitrary programs, etc.

Current Status

DbgShell has been in “prototyping mode” for a long time. I have spent a lot of time figuring how something could or should be done, but not necessarily “finishing” everything. There are a huge number of TODOs in the current code. So although it has started to become actually useful, the project is still pretty green. However, it can definitely demonstrate enough to give you a good taste of what it should be like.

Current Deficiencies

• The biggest deficiency currently is that it does not support kernel mode well (if you are already in the proper context, you can display values, but you can’t change context from within DbgShell, and the namespace is not wired up).
• Although you can load and execute traditional debugger extensions in the usual way, there are still many windbg commands missing.
• Remotes are not supported: the dbgeng API supports connecting to a remote debugger. Unfortunately, the symbol and type information exposed by the dbgeng API is critically insufficient for DbgShell’s needs, so DbgShell uses the dbghelp API. Unfortunately, there is no such thing as remote dbghelp. We will need to work with the debugger team to solve this problem.