Navigating the Concord API

The Concord API is large enough that it can be a bit overwhelming at first glance. Here are a few hints which may make navigating the API easier:

1. When deciding what interfaces to implement, we have organized all the interfaces by the category of component that implements the interface. If you look in the native API header file (vsdebugeng.h) you can see each interface listed by section, as well as a description of what that category of component does. For example, to find all the base debug monitor interfaces, look for the string "// Base debug monitors interfaces".
2. When looking for methods to call, ignore interfaces. The Concord API is exposed to callers as methods on classes rather than interface methods.
3. Findstr in vsdebugeng.h: even if you are implementing a Concord component in managed code, sometimes the fastest way to find the method that you want is to look for strings in vsdebugeng.h. Since the API is the same between native and managed code, if you find the native API, it will work in managed also.
4. Browse the references in Microsoft.VisualStudio.Debugger.Engine – this is the flip side of #3, even if you are consuming the Concord API from native code, Visual Studio ships really nice support for browsing through managed APIs.

Commonly encountered 'Dkm' objects and their purpose:

DkmProcess

This is the process being debugged. Some of the more important information it contains is the list of threads, list of runtime instances, information about the process itself (operating system information and or dump file information), as well as information used by the Dispatcher to track the connection to the msvsmon process debugging the process if remote or 64-bit debugging.

A DkmProcess can only be created by a Base Debug Monitor.

DkmModuleInstance

A module instance represents an executable section of code that has been loaded into the process being debugged. When debugging Native code or .NET code, a module instance corresponds to a .dll or .exe file.

A DkmModuleInstance can only be created by a Runtime or Base Debug Monitor.

DkmRuntimeInstance

The runtime instance corresponds to a 'runtime' being debugged. Example runtimes are native (DkmNativeRuntimeInstance) and the CLR (DkmClrRuntimeInstance). There is also a DkmCustomRuntimeInstance that can be used to write Debug Monitors for other types of runtimes. An interpreter is an example of a runtime that can be debugged. Each runtime (and DkmRuntimeInstance) maps to a specific Runtime Debug Monitor and serves as a gateway to the debug monitor that other components can call.

A DkmRuntimeInstance can only be created by a Runtime Debug Monitor

DkmThread

A thread in the process being debugged.

A DkmThread can only be created by a Base Debug Monitor