New Debug Engine Sample!

  • Article

I just released a new sample for writing a Visual Studio Debug Engine. The new engine sample is available at: https://code.msdn.microsoft.com/Visual-Studio-Debug-Engine-c2e21c0e

This sample ships under the Microsoft Public License which means there is no warentee or support. Essentially, use of the sample is at your own risk.

A debug engine is a component that plugs into Visual Studio's debugger UI and actually does the debugging for whatever is being debugged. Each debug engine is responsible for debugging a particular architecture or runtime. Why so much interest in writing one? Each runtime architecture, whether it be native code running on a processor, a jit compiled runtime, or an interpreter, requires a debug engine that understands that architecture.

A custom debug engine is required when adding debugging support for a new platform technology into Visual Studio. .Net language implementers should implement an Expression Evaluator instead which integrates into the existing .Net debug engine.

The Visual Studio Debugger is split up architecturally into a few pieces:

1) The debugger UI: the windows and commands the user actually interacts with. A good example of this is the watch window or the little red circle that appears in the text editor as a breakpoint.

2) The SDM (session debug manager): “ A debug engine multiplexer” Admittedly, that’s a confusing explanation.
Essentially, the SDM’s job to combine all of the events and commands for the various debug engines into one unified stream for the UI. The debugger UI only displays one ”view” of what is being debugged at a time. Even if the user is debugging multiple processes or threads, they are only looking at one of them.

3) Debug Engines – the components that perform the actual debugging of a debuggee. For instance, a native debug engine would be responsible for debugging native win32 applications. A script debug engine would be responsible for debugging jscript or vbscript. A CLR debug engine would be responsible for debugging .Net applications running on the CLR. A hypothetical Perl engine could be responsible for debugging Perl… and on and on

Visual Studio Debug Engines implement and interact with a set of interfaces called AD7 which stands for Active Debugging 7. AD7 is publically documented here: https://msdn2.microsoft.com/en-us/library/bb147088.aspx

This new debug engine sample demonstrates the majority of AD7 and debugs native win32 applications. It currently supports: launching, attaching, breakpoints, basic callstack walking, module and thread enumeration, and debug properties (parameters and locals). It does not implement more advanced features such as conditional breakpoints and tracepoints.

The sample is split into three separate projects:

1) A front end implemented in C# which implements the AD7 interfaces and interacts with the SDM. The root object of this project is AD7Engine which implements IDebugEngine2. This project is called Microsoft.VisualStudio.Debugger.SampleEngine.

2) A back end implemented in mixed mode C++ which interacts with the win32 debugging API and DIA, the public symbol interfaces. This project is called Microsoft.VisualStudio.Debugger.SampleEngineWorker.

3) A Visual Studio Addin which is used to launch Visual C++ projects using the new engine. This project is named ProjectLauncher. It adds a new command button “ProjectLauncher” to the Visual Studio Tools menu which will launch a form that displays the current projects in Visual Studio that can be launched with the new engine.

Currently, the documentation for the new engine is the comments in the code. Iwill be adding new blog entries and walkthroughs as time allows. Please check back with my blog as well as the sample page for future updates and walkthroughs.