Core Interfaces
Note
This article applies to Visual Studio 2015. If you're looking for the latest Visual Studio documentation, see Visual Studio documentation. We recommend upgrading to the latest version of Visual Studio. Download it here
The following interfaces are the core interfaces for extending debugger by using the Visual Studio SDK.
Discussion
These interfaces are primarily used to create the debug engine (DE). They are organized here by categories:
-
The entities that can implement the interfaces are:
Debug Engine (DE)
Port Supplier (PS)
Expression Evaluator (EE)
Visual Studio (VS)
Breakpoints
These interfaces are related to the implementation and tracking of breakpoints.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugBoundBreakpoint2 | DE | Represents a breakpoint bound to a memory location. |
| IDebugBreakpointBoundEvent2 | DE | Sent by the DE when a breakpoint is bound to a memory location. |
| IDebugBreakpointChecksumRequest2 | VS | Represents a document checksum for a breakpoint request. |
| IDebugBreakpointErrorEvent2 | DE | Sent by the DE when a breakpoint fails to be bound to a memory location. |
| IDebugBreakpointEvent2 | DE | Sent by the DE when a breakpoint is reached. |
| IDebugBreakpointRequest2 | VS | Represents a request for a breakpoint; used in creating a pending breakpoint. |
| IDebugBreakpointRequest3 | VS | Represents a request for a breakpoint; used in creating a pending breakpoint. |
| IDebugBreakpointResolution2 | DE | Represents the information used to bind a breakpoint. |
| IDebugBreakpointUnboundEvent2 | DE | Sent by the DE when a breakpoint is unbound from a memory location. |
| IDebugErrorBreakpoint2 | DE | Represents an invalid breakpoint (returned by IDebugBreakpointErrorEvent2). |
| IDebugErrorBreakpointResolution2 | DE | Represents the resolution information about an invalid breakpoint. |
| IDebugFunctionPosition2 | DE | Represents a position in a function where a breakpoint is set. |
| IDebugPendingBreakpoint2 | DE | Represents a breakpoint that is to be bound; used in creating a bound breakpoint. |
| IEnumDebugBoundBreakpoints2 | DE | Represents an enumeration over a set of bound breakpoints. |
| IEnumDebugErrorBreakpoints2 | DE | Represents an enumeration over a set of breakpoints that could not be bound to a memory location. |
Contexts
These interfaces represent various kinds of contexts within the program being debugged.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugCodeContext2 | DE | Represents the starting position of a code instruction. |
| IDebugCodeContext3 | DE | Extends the IDebugCodeContext2 interface to enable the retrieval of module and process interfaces. |
| IDebugDocumentContext2 | VS, DE | Represents a position in a document. |
| IDebugExpressionContext2 | DE | Represents the context in which to evaluate an expression. |
| IDebugMemoryContext2 | DE | Represents the starting location in memory of a collection of bytes. |
| IDebugStackFrame2 | DE | Represents a stack frame context at a breakpoint or exception. |
| IDebugStackFrame3 | DE | Represents a stack frame context at a breakpoint or exception. |
| IEnumDebugCodeContexts2 | DE | Represents an enumeration over a set of code contexts. |
Core Server
These interfaces represent the machine on which a program is being debugged. These are implemented by Visual Studio but can be called into by debug engines.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugCoreServer2 | VS | Provides access to ports and port suppliers as well as information about the computer. |
| IDebugCoreServer3 | VS | Represents an IDebugCoreServer2 that supports remote debugging. |
Debug Engines
These interfaces represent debug engines and their associated events.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugEngine2 | DE | Represents a custom debug engine. |
| IDebugEngine3 | DE | Represents a custom debug engine that supports loading of symbols, JustMyCode, and exceptions. |
| IDebugEngineCreateEvent2 | DE | Sent by each new instance of the DE to indicate it is ready to handle debugging tasks. |
| IDebugEngineLaunch2 | DE | Represents a custom debug engine that supports launching programs. |
| IDebugProgramEngines2 | DE, PS | Represents a program node that handles multiple debug engines. |
| IDebugQueryEngine2 | DE | Provides a way for the SDM to obtain an interface to the debug engine from a thread, program, or stack frame. |
Documents
These interfaces represent documents (source files) and their associated elements.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugActivateDocumentEvent2 | DE | Sent by the DE to request a document to be opened. |
| IDebugDisassemblyStream2 | DE | Represents a stream of disassembled instructions from a document. |
| IDebugDocument2 | VS, DE | Represents a document supplied by the DE, specifying a name and a class ID (CLSID). |
| IDebugDocumentChecksum2 | DE, EE | Represents a checksum for a debug document and enables passing the checksum between components. |
| IDebugDocumentContext2 | VS, DE | Represents a document context, a position within a document corresponding to a particular statement and code context. |
| IDebugDocumentPosition2 | VS, DE | Represents a general position within a document. |
| IDebugDocumentPositionOffset2 | VS | Represents a position in a source file as a character offset. |
| IDebugDocumentText2 | VS, DE | Represents a text document supplied by the DE (derived from IDebugDocument2), supplying the actual text. |
| IDebugDocumentTextEvents2 | DE | Sent by the DE to specify changes to a source file that is in memory. |
Events
These interfaces represent all events that are sent between the DE and the session debug manager (SDM).
| Interface | Implemented by | Description |
|---|---|---|
| IDebugActivateDocumentEvent2 | DE | Sent by the DE to request a document to be opened. |
| IDebugBeforeSymbolSearchEvent2 | DE | The debug engine (DE) sends this interface to the session debug manager (SDM) to set the status bar message during symbol loads. |
| IDebugBreakEvent2 | DE | Sent by the DE when a break in the program has been completed. |
| IDebugBreakpointBoundEvent2 | DE | Sent by the DE when a breakpoint is bound. |
| IDebugBreakpointErrorEvent2 | DE | Sent by the DE when a breakpoint fails to be bound. |
| IDebugBreakpointEvent2 | DE | Sent by the DE when a breakpoint is reached. |
| IDebugBreakpointUnboundEvent2 | DE | Sent by the DE when a breakpoint is unbound. |
| IDebugCanStopEvent2 | DE | Sent by the DE to determine whether it should stop at a particular location. |
| IDebugDocumentTextEvents2 | DE | Sent by the DE to specify changes to a source file that is in memory. |
| IDebugEngineCreateEvent2 | DE | Sent by each new instance of the DE to indicate it is ready to handle debugging tasks. |
| IDebugEntryPointEvent2 | DE | Sent by the DE to indicate the program being debugged is ready to execute the first instruction. |
| IDebugErrorEvent2 | DE | An interface that is used by other event interfaces, which might return an error, to provide human-readable error messages. |
| IDebugEvent2 | DE, PS | Base interface from which all other event interfaces are derived. |
| IDebugEventCallback2 | VS | Represents an interface implemented by the SDM to which events (expressed as objects implementing a particular event interface) are sent. |
| IDebugExceptionEvent2 | DE | Sent by the DE when an exception has occurred in the program being debugged. |
| IDebugExpressionEvaluationCompleteEvent2 | DE | Sent by the DE when an asynchronous expression evaluation is complete. |
| IDebugFindSymbolEvent2 | OBSOLETE. DO NOT USE. | |
| IDebugInterceptExceptionCompleteEvent2 | DE | Sent by the DE when processing for an intercepted exception has been completed. |
| IDebugLoadCompleteEvent2 | DE | Sent by the DE when a program has completed loading. |
| IDebugMessageEvent2 | DE | Sent by the DE to have the IDE display an informational message to the user. |
| IDebugModuleLoadEvent2 | DE | Sent by the DE when a module is loaded or unloaded. |
| IDebugNoSymbolsEvent2 | DE | Signals the Visual Studio debugger UI to warn the user that symbols could not be located for the launched executable. |
| IDebugOutputStringEvent2 | DE | Sent by the DE to have the IDE display an arbitrary string. |
| IDebugPortEvents2 | VS, DE | Sent by a port to communicate port events to any listener. |
| IDebugProcessCreateEvent2 | DE, PS | Sent by the DE or port when a process has been created. |
| IDebugProcessDestroyEvent2 | DE, PS | Sent by the DE or port when a process has been destroyed. |
| IDebugProgramCreateEvent2 | DE, PS | Sent by the DE or port when a program has been created. |
| IDebugProgramDestroyEvent2 | DE, PS | Sent by the DE or port when a program has been destroyed. |
| IDebugProgramDestroyEventFlags2 | DE | Enables a debug engine to override the default behavior of the Visual Studio UI when you end a debug session. |
| IDebugProgramNameChangedEvent2 | DE | Sent from the debug engine (DE) to the session debug manager (SDM) when the name of a program changes. |
| IDebugPropertyCreateEvent2 | DE | Sent by the DE when a new property (represented by the IDebugProperty2 interface) has been created. |
| IDebugPropertyDestroyEvent2 | DE | Sent by the DE when a property has been destroyed. |
| IDebugReturnValueEvent2 | DE | Sent by the DE when stepping out of or over a function so the return value can be correctly displayed. |
| IDebugSettingsCallback2 | VS | Enables debug engines to read metric settings remotely. |
| IDebugStepCompleteEvent2 | DE | Sent by the DE when a step into, over, or out of an instruction has been completed. |
| IDebugSymbolSearchEvent2 | DE | Sent by the DE to indicate the success or failure of loading symbols for a module. |
| IDebugThreadCreateEvent2 | DE | Sent by the DE when a thread has been created. |
| IDebugThreadDestroyEvent2 | DE | Sent by the DE when a thread has been destroyed. |
| IDebugThreadNameChangedEvent2 | DE | Sent by the DE when a thread has changed its name. |
Expressions
These interfaces represent expressions to be evaluated in a particular context.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugExpression2 | DE | Represents an expression to be evaluated. Obtained from the IDebugExpressionContext2 interface. |
| IDebugExpressionContext2 | DE | Represents a context in which an expression is evaluated. Obtained from the IDebugStackFrame2 interface. |
| IDebugExpressionEvaluationCompleteEvent2 | DE | Sent by the DE when an asynchronous expression evaluation is complete. |
Memory
These interfaces represent sequences of bytes in memory.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugMemoryBytes2 | DE | Represents a sequence of bytes in memory that can be read from or written to. |
| IDebugMemoryContext2 | DE | Represents a location in memory of a sequence of bytes. |
Modules
These interfaces represent a module, which corresponds to an executable or .DLL file.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugModule2 | DE | Represents a single executable or DLL. |
| IDebugModule3 | DE | Represents an IDebugModule2 that supports symbols. |
| IDebugModuleLoadEvent2 | DE | Sent by the DE when a module is loaded or unloaded. |
| IDebugSourceServerModule | DE | Represents the source server information that is contained in a PDB file. |
| IEnumDebugModules2 | DE | Represents an enumeration over a set of modules that are known by an IDebugProgram2. |
Ports
These interfaces represent ports and port suppliers.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugDefaultPort2 | VS, PS | Represents the default port on the local computer. |
| IDebugFirewallConfigurationCallback2 | VS | Enables a debug engine that uses DCOM to ask the Visual Studio UI to make sure that the firewall will not block remote debugging. |
| IDebugPort2 | VS, PS | Represents a port. |
| IDebugPortEvents2 | PS | Sent by a port to communicate port events to any listener. |
| IDebugPortEx2 | PS | Represents a port that can launch and terminate processes. |
| IDebugPortNotify2 | PS | Used to register and unregister programs with a port; allows the port to track programs currently being debugged. |
| IDebugPortPicker | PS | Represents a customized UI for selecting the port. |
| IDebugPortRequest2 | VS | Represents a request for a port from which a new port will be created or located. |
| IDebugPortSupplier2 | PS | Represents a supplier of ports. |
| IDebugPortSupplier3 | PS | Represents a supplier of ports that can persist (save to disk) information about the ports it created. |
| IDebugPortSupplierDescription2 | PS | Enables the Visual Studio UI to display text inside the Transport Information section of the Attach to Process dialog box. |
| IDebugWindowsComputerPort2 | VS | Allows querying for information about the target computer. |
| IEnumDebugPorts2 | VS, PS | Represents an enumeration over a set of ports. |
| IEnumDebugPortSuppliers2 | VS | Represents an enumeration over a set of port suppliers. |
Processes
These interfaces represent processes, a single executable that contains one or more programs.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugProcess2 | PS, DE | Represents a process that is running on a computer. |
| IDebugProcess3 | PS, DE | Represents a process that actively supports debugging (used to replace Step, Continue, and Execute methods on the IDebugProgram2 interface). |
| IDebugProcessCreateEvent2 | DE, PS | Sent by the DE or port when a process has been created. |
| IDebugProcessDestroyEvent2 | DE, PS | Sent by the DE or port when a process has been destroyed. |
| IDebugProcessEx2 | PS | Represents a process that must track which session is attached to it. |
| IEnumDebugProcesses2 | PS | Represents an enumeration of a set of processes on a port. |
Programs
These interfaces represent programs, logical units of execution that do not necessarily correspond to a physical executable or module.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugEngineProgram2 | DE | Represents an IDebugProgram2 that needs to work in concert with other programs being debugged at the same time. |
| IDebugProgram2 | DE, PS | Represents a logical unit of execution. |
| IDebugProgramCreateEvent2 | DE, PS | Sent by the DE or port when a program has been created. |
| IDebugProgramDestroyEvent2 | DE, PS | Sent by the DE or port when a program has been destroyed. |
| IDebugProgramEngines2 | DE, PS | Represents an IDebugProgramNode2 that can be handled by multiple debug engines. |
| IDebugProgramEx2 | PS | Represents an IDebugProgram2 that must be able to track which session is attached to it. |
| IDebugProgramHost2 | DE, PS | Represents an IDebugProgram2 that can return information about the process in which it is running. |
| IDebugProgramNode2 | DE, PS | Represents a program that can be debugged. |
| IDebugProgramNodeAttach2 | DE, PS | Allows a program node to be notified of an attempt to attach to the associated program. |
| IDebugProgramProvider2 | DE | Provides a way for the SDM to query a DE about the programs controlled by that DE. |
| IDebugProgramPublisher2 | VS | Used by DEs to register programs with the SDM to show they are being debugged. |
| IDebugProviderProgramNode2 | DE, PS | Represents an IDebugProgramNode2 that can marshal interfaces across thread or process boundaries. |
| IEnumDebugPrograms2 | DE, PS | Represents an enumeration of a set of programs. |
Properties
These interfaces represent properties, a value associated with a particular context, usually the result of an expression evaluation.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugCustomViewer | EE | Represents an IDebugProperty2 that can display its value in a custom way. |
| IDebugProperty2 | DE | Represents a value of a stack frame, document, or the result of an expression evaluation. |
| IDebugProperty3 | DE | Represents an IDebugProperty2 that supports arbitrarily long strings. |
| IDebugPropertyCreateEvent2 | DE | Sent by the DE when a new property (represented by the IDebugProperty2 interface) has been created. |
| IDebugPropertyDestroyEvent2 | DE | Sent by the DE when a property has been destroyed. |
| IDebugReference2 | DE | Represents a reference to a property which can exist outside any particular stack frame. |
| IEnumDebugPropertyInfo2 | DE | Represents an enumeration over a set of DEBUG_PROPERTY_INFO structures which describe variables, registers, parameters, and expressions. |
| IEnumDebugReferenceInfo2 | DE | Represents an enumeration over a set of DEBUG_REFERENCE_INFO structures. |
Stack Frames
These interfaces represent a stack frame, a context in which a breakpoint or exception has occurred.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugStackFrame2 | DE | Represents a context in which a breakpoint or exception has occurred. |
| IDebugStackFrame3 | DE | Represents an IDebugStackFrame2 which can handle intercepted exceptions. |
| IEnumCodePaths2 | DE | Represents an enumeration over the set of CODE_PATH structures which specify the function call sequence used to arrive at a particular stack frame. |
| IEnumDebugFrameInfo2 | DE | Represents an enumeration over a set of FRAMEINFO structures, which describe stack frames. |
Threads
These interfaces represent threads and their associated events.
| Interface | Implemented by | Description |
|---|---|---|
| IDebugThread2 | DE | Represents a thread of execution. |
| IDebugThreadCreateEvent2 | DE | Sent by the DE when a thread has been created. |
| IDebugThreadDestroyEvent2 | DE | Sent by the DE when a thread has been destroyed. |
| IDebugThreadNameChangedEvent2 | DE | Sent by the DE when a thread has changed its name. |
| IEnumDebugThreads2 | DE | Represents an enumeration over a set of threads. |
Type Visualizers
These interfaces provide support for type visualizers. These interfaces are typically implemented by an expression evaluator.
| Interface | Implemented by | Description |
|---|---|---|
| IEEDataStorage | EE | Represents an array of bytes to be presented to a type visualizer. |
| IPropertyProxyEESide | EE | Provides methods for getting access to data to be passed to a type visualizer. |
| IPropertyProxyProvider | EE | Represents a property that provides access to IPropertyProxyEESide implementations. |