About the Debugging API
The common language runtime (CLR) debugging API enables tools vendors to write debuggers to debug applications that run in the CLR environment. The code to be debugged can be any kind of code that the CLR supports.
The CLR debugging API is implemented primarily with unmanaged code. Therefore, the debugging API is presented as a set of COM interfaces. The API consists of a collection of COM objects and interfaces that are implemented by the CLR, and a collection of COM callback interfaces that must be implemented by the debugger. Because these debug interfaces are all based on COM, debugger programs can be easily extended to enable remote debugging by using distributed COM (DCOM).
API Categories
The debugging API includes the following three groups of interfaces, all used typically by a CLR debugger and all implemented as unmanaged code:
Interfaces that support debugging of CLR applications.
Interfaces that provide access to symbolic debug information, which is typically stored in program database (PDB) files.
Interfaces that support querying of the processes and application domains on a computer.
The debugging API relies on two additional sets of interfaces:
Metadata API to handle inspection of static program information such as classes and method type information.
Symbol store API to support source-level debugging for managed code debuggers.
The debugging interfaces can also be organized into the functional categories shown in the following table.
API category |
Description |
|---|---|
Registration |
Interfaces that the debugger calls to register with the CLR and to request notification when specific events occur. |
Notification |
Callback interfaces that the CLR uses to notify the debugger of various events and to return requested information. These interfaces must be implemented by the debugger. |
Breakpoint |
Interfaces that the debugger calls to retrieve information about breakpoints. |
Execution |
Interfaces that the debugger calls to control the execution of the debuggee and to access call stacks. |
Information |
Interfaces that the debugger calls to obtain information about the debuggee. |
Enumeration |
Interfaces that the debugger calls to enumerate objects. |
Modification |
Interfaces that the debugger calls to modify the code that is being debugged. |
Supported Environments
CLR debugging facilities are available on all processors and operating systems that the CLR supports, with the following exceptions:
Edit and Continue and mixed-mode debugging are not supported on 64-bit operating systems. The SetIP methods (ICorDebugILFrame::SetIP and ICorDebugNativeFrame::SetIP) have additional restrictions on 64-bit operating systems. The remaining functionality is equivalent on all processors, allowing for processor-specific data representations (pointer sizes, register contexts, and so on).
Edit and Continue and mixed-mode debugging are not supported on Win9x-based operating systems. With a few specific exceptions, which are noted in the documentation of individual functions, the remaining functionality should be equivalent on all operating systems.