Core Interfaces

The following interfaces are the core interfaces for extending the 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:

• Breakpoints

• Contexts

• Core Server

• Debug Engines

• Documents

• Events

• Expressions

• Memory

• Modules

• Ports

• Processes

• Programs

• Properties

• Stack Frames

• Threads

• Type Visualizers

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.

See Also

Reference

API Reference (Visual Studio Debugging)

Other Resources

Creating a Custom Debug Engine