What is the standard/preferred way to write new extensions for Windbg (from the Microsoft Store)?

Question

Background:

Windbg currently ships in two "flavours", the first (and well-known) is the version that ships with the Windows SDK. The second, and relatively more recent, is the version that ships via the Microsoft Store.

Current Understanding:

As I understand it, these are the preferred flavours for Windbg (old), in order of preference:

• Wdbgexts - Old and busted and should no longer be used

• DbgEng - Supported by both Windbg (old) and Windbg (new), as far as I can tell.

• Engext - The preferred "new" hotness that ships with the SDK but not with new Windbg (from the Microsoft store).

Ask:

For Windbg (new) (formally called DbgX, I think?), specifically, it would appear that Engext and DbgX (C#) are the preferred means to write extensions (or interops); however, since Windbg (new) does not ship with Engext (only the SDK does), I'm wondering if Engext is still the preferred method for writing extensions Windbg (new) - or - if there's a new pattern that should be followed, of which I'm not aware (yet)? (It's worth noting that the Engext example linked is from 5 years ago and Windbg (new) was in preview, then.)

In other words, it's hard to write an extension that depends on Engext, when the Microsoft Store version of the debugger does not ship with it; so, one has to download both the SDK and the store version of Windbg to be able to use Engext.

This disparity in header inclusion would lead one to assume (at least, I do) that - maybe - there's a new preferred pattern for writing Windbg Extensions (such as writing extensions in C# or JavaScript, for example) that I'm not readily able to see is - actually - the preferred means, today.

Is Engext still the preferred means for new Windbg Extensions for Windbg (new) - or - should new Windbg extensions be written in, say, C# or JavaScript or the like, given that Windbg (new) doesn't ship with Engext "out of the box"?

Answer 1

How you write an extension for WinDbg these days really depends on what you want to do with the extension. There are significantly more options today than the IDebug* DbgEng APIs or EngExtCpp.

What do you mean by an "extension"...? For the debugger today, there are multiple things you might mean by this. There are "top edge extensions" (add a new bang command, change the way data is visualized, script the debugger, etc...) and there are "bottom edge extensions" that you might see referred to as plug-ins (allow the debugger to open a new file format, add support for a new symbol format, add support for targeting a different operating system, etc...).

Most folks probably are interested in the former (top edge). For that, the general pattern that we recommend these days:

• If you can use NatVis, use it. NatVis allows changes in the way data is visualized. It's supported by both WinDbg and Visual Studio. It can be embedded in PDBs. Documentation can be found in the VS docs at https://learn.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects?view=vs-2022
• If that doesn't work, go to a data model extension using JavaScript. JS extensions are incredibly powerful, easier to write than C/C++, are always interruptable, and can't crash the debugger if you make a mistake. There are several JS extensions included with the debugger that can be used for reference (e.g.: ImageInfo.js, LinuxKernel.js, etc...). Here are some documentation / reference links of interest:
  • JS model: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/javascript-debugger-scripting.
  • Debugger data model: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/data-model-cpp-overview
  • LINQ and the data model: https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/using-linq-with-the-debugger-objects
  • Channel 9 Video Re: dx / data model: https://learn.microsoft.com/en-us/shows/defrag-tools/138-debugging-dx-command-part-1 and https://learn.microsoft.com/en-us/shows/defrag-tools/139-debugging-dx-command-part-2.
  • Useful blog post: https://doar-e.github.io/blog/2017/12/01/debugger-data-model/
  • Various samples: https://github.com/microsoft/WinDbg-Samples
  • Channel 9 Video About JS: https://learn.microsoft.com/en-us/shows/defrag-tools/170-debugger-javascript-scripting
  • Channel 9 Video About JS in the new UI: https://learn.microsoft.com/en-us/shows/defrag-tools/184-javascript-in-windbg-preview
• If that doesn't work because you need access to APIs or features not available in JavaScript, write a data model extension in C/C++. While there are COM APIs to do this, the easiest way is to use the data model client C++17 library.
  • Documentation, source, etc...: https://github.com/microsoft/WinDbg-Libraries/tree/master/DbgModelCppLib
  • NuGet: https://www.nuget.org/packages/Microsoft.Debugging.DataModel.CppLib
  • Hello World level sample: https://github.com/microsoft/WinDbg-Samples/tree/master/DataModelHelloWorld/Cpp/SimpleIntroClientLibrary. Note that this sample also has a JS and C/COM version in adjacent directories in the GitHub repo
• If, for some reason, none of that works, fall back to a C/C++ extension using various legacy APIs (e.g.: the IDebug* DbgEng APIs, EngExtCpp, etc...)

One additional thing I'll mention about "data model extensions" is that via a manifest, it's possible for them to add icons to the WinDbg "Extensions" tab of the ribbon to present query results. There aren't many of those today -- but if you kernel debug (Windows or Linux), you might notice one or two of those available today. Documentation regarding that can be found at: https://github.com/microsoft/WinDbg-Samples/blob/master/Manifest/README.MD

For "lower edge" plug-ins that teach the debugger about new file formats, symbol formats, etc... there are an entirely different set of APIs you might see referred to as "target composition". The idea with that is that a debugger "target" is effectively a container of interdependent "services" (e.g.: virtual memory service, process enumeration service) which can be manipulated. While the detailed documentation for these interfaces hasn't yet been written, the header has reasonable comments, there are some excellent samples, and a few blog posts are available:

• Blog post: https://www.timdbg.com/posts/whats-the-target-model/
• NuGet package: https://www.nuget.org/packages/Microsoft.Debugging.TargetModel.SDK
• TextDump sample (allows the debugger to "debug" a text file log of previous debugger output): https://github.com/microsoft/WinDbg-Samples/tree/master/TargetComposition/TextDump

Probably the best sample we have which spans both of these areas is the Symbol Builder sample at https://github.com/microsoft/WinDbg-Samples/tree/master/TargetComposition/SymBuilder. It is an extension which is both upper and lower edge. At the upper edge, it presents a data model API (which is accessible via JavaScript) to create and alter synthetic symbols. At the lower edge, it presents a new "in memory" symbol format to the debugger so that synthetic symbols work everywhere in the debugger just like PDBs. It even supports importing from public PDBs to allow alteration or addition of symbols.

Answer 2

It really depends on your use case, but basically they are all valid and there's no preferred or official way of making a Windbg extension.

If you want to leverage the engine directly from native code; add functionalities to the engine itself; embed the engine in your application, etc.

• DbgEng: that's the low level API to use the engine itself. Powerful but can be hard to use. And let's be honest, some parts of the documentation are horrendous (or sometimes just non-existing).

• Engext: a wrapper around the dbgeng API. Simplify some stuff (remove boilerplate code and greatly simplify the handling of some parts of the engine); may be problematic if, at some point, you want to "get down" to the lower level API (it's possible but sometimes the wrapper gets in the way, IMO).

• DbgX: tried it a bit but not that much. From my point of view it's pretty much the same as EngExt but with C# instead of C++. From what I remember it's more about embedding the engine in your app than programming an engine extension (might be possible though).

One shot stuff; It's basically a C wrapper around the engine where you don't have access to the engine internals and can't tweak anything.

• Wdbgexts: it still has its use for specific scenarios, but from my points of view, it's mostly superseded by JS (not from an usage point of view, but from what it can do). It's way more limited than using the engine itself.

Scripting!

• JavaScript: If you just want to use the engine (and possibly add new commands by combining multiple stuff that the engine can do) then for me it's the way to go. It has some quirks - the learning curve is not that easy and the documentation is so-so - and stuff that still leave to desire (executing JS code when a breakpoint is hit is just a major pain in the ...).

The debugger model is a super nice addition to what's already there. I converted some of my previous extensions to JS and don't regret anything. Depending on what you want to do, it might be super verbose or just outright impossible (in which case it's just better to stay with native extensions).

---

I surmise that you got confused by the fact that there's a dbgeng.dll (which is the debugging engine itself) and a similarly named API but not a Engext.dll or something approaching. As explained in my comment, engext is just a code wrapper around the low-level API. You can still use the latter with the "new" Windbg.