The Debugger Extension, Part 1: What Is a DbgEng Extension?
November 22nd, 2005
A better question to start off might be: “what is DbgEng?” Frequent visitors may have seen me refer to WinDbg and the Debugging Tools for Windows somewhat interchangably. There are actually two other debuggers in the package called CDB and NTSD. CDB, NTSD, and WinDbg are all written on top of the same debugger engine, implemented in dbgeng.dll.
An extension for the debugger engine is a dll with a specific set of exported functions. Commands that are callable from the debugger are implemented as additional exported functions. SOS, SieExtPub, and other modules I may have mentioned before are all debugger extensions in this vein. The full syntax for calling an extension function from within the debugger is:
![module].[function] [arguments]
The extension module name is only really necessary if there is a naming collision. For example, if you have several extensions loaded that all define a !help function, you can call the !help function in Son of Strike by typing !SOS.help.
The basics of Writing a Debugger Extension
The DbgEng API is a set of COM interfaces that allow you to interact with both the debugger and the process or crash dump being debugged. It’s a little difficult to find documentation for the interfaces online, but the help files that come with the debugging tools are reasonably complete. The header files in the SDK fill in the remaining gaps. You can get some information from this PowerPoint document.
Understanding the COM interfaces is definitely the simplest aspect of writing an extension, at least from the perspective of developers who have been spending their lives writing code in user mode—not even to mention those accustomed to managed code and Visual Studio. DbgEng requires that your extension be built using the Windows Driver Development Kit (DDK) build environment. One thing I would definitely recommend is DDKBUILD, a freeware batch file that allows you to use the DDK build environment from a Visual Studio makefile project.
As you can see, writing an extension remains something of an arcane activity. Eran Sandler has threatened to create a framework for writing managed debugger extensions, and I hope he does. That would be cool.
It has recently become at least slightly easier to create extensions, in terms of language if not environment. In the most recent debugger update, I found this in the release notes:
New EngExtCpp C++ extension framework … This is a Developer Preview, and APIs are subject to change.
This is the framework I will be using. After setting up the sources, makefile, .def file, and .rc file for my project (I recommend just copying and editing these from one of the debugger SDK samples), all I need to do to create a working—but useless—extension is to define two files.
// ------------------------------------------------------
// dmext.h
//
#pragma once
#include "engextcpp.hpp"
class EXT_CLASS : public ExtExtension
{
public:
EXT_CLASS();
EXT_COMMAND_METHOD(foo);
};
// ------------------------------------------------------
// dmext.cpp
//
#include "stdafx.h"
#include "dmext.h"
EXT_DECLARE_GLOBALS();
EXT_CLASS::EXT_CLASS()
{
}
EXT_COMMAND(foo, "Sample extension command", "")
{
this->Out("Hello World.\n");
}
In the next post, after I plead with you for a while that this is still a good idea, we’ll set up a sample problem set to work with.
