How can I use ICorDebug?

ICorDebug, the managed debugging API,  is a public API and anybody can use it to write a managed debugger.

 

However, it’s also a very large and scarcely documented API. V1.1 had about 250 methods, and v2.0 has about 300 methods, and there’s nothing in MSDN about it. So despite our claims, we recognize that it’s very difficult to actually write a good tool against it.

 

Here are some resources for writing tools against ICorDebug:

1) Jon Shute’s Debugging walkthrough: I came across some great articles for a walkthrough on ICorDebug at this site: https://blogs.chimpswithkeyboards.com/jonshute/category/2.aspx  . These things look like an excellent starting place (though I haven’t actually gone through these myself to verify their correctness, but they look right when I skim over them).

2) CorDebug.idl – this is the official idl file for the ICorDebug API. It describes the cordbg interfaces at a per-function scope.  Unfortunately, this doesn’t describe how to use the functions together to perform anything useful.

3) DebugRef.doc in the SDK.  This includes some scenario information beyond what’s in CorDebug.idl. This is in the Tool Developers Guide (TDG) at \docs.

4) The Cordbg sample. We ship the source code to Cordbg.exe (the command line debugger in the SDK, implemented in unmanaged C++). This is in the Tool Developers Guide (TDG) at \Samples\debugger. This is probably the best place to see examples of stacktracing and printing objects.

5) The MDbg sample . This is a managed version of Cordbg written in C#. It includes a managed set of wrappers for ICorDebug. This is probably the best thing to actually write against.

6) The CLR shared source (also called “Rotor”).  The shared source is available at: https://www.microsoft.com/downloads/details.aspx?FamilyId=3A1C93FA-7462-47D0-8E56-8DD34C6292F0&displaylang=en   It includes an approximate implementation of the managed debugging services (look under the debug\di directory for things implementing ICorDebug*). Sometimes having the source around can shed light on things.

7) This blog (https://blogs.msdn.com/jmstall/). I’ll try to answer the common questions, and use this blog to preview new retro-specs (v1.1 specs created after we shipped in an attempt to plug a spec hole). Your feedback can also let  us know what parts of our API are confusing and need more clarification. Also, I have an ICorDebug- specific category on the blog, https://blogs.msdn.com/jmstall/category/7367.aspx/rss. You can subscribe to just this feed if you just want the ICorDebug trivia.

8)   [Update:7/26/06] The ICorDebug forum! This is a public forum for asking, answering, and announcing things about ICorDebug / Mdbg. We hope this will be a great resource for managed debugger authors.

 

I hope that helps. I realize this is still pretty incomplete, but rest assured that we’re trying to improve it.  If I come across other resources, I'll try to come back and update this page with them. 

Now go out and write great tools for .NET and help us make it the best platform out there.