Share via


Core Interfaces

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:

  • 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