DkmRuntimeBreakpoint Class

  • Reference

Definition

Namespace:
Microsoft.VisualStudio.Debugger.Breakpoints
Assembly:
Microsoft.VisualStudio.Debugger.Engine.dll

Low-level breakpoint object which is supported by debug monitors.

Derived classes: DkmRuntimeHardwareDataBreakpoint, DkmRuntimeInstructionBreakpoint, DkmRuntimeClrDataBreakpoint, DkmRuntimeCustomDataBreakpoint

public ref class DkmRuntimeBreakpoint abstract : Microsoft::VisualStudio::Debugger::DkmDataContainer, IDisposable
[System.Runtime.InteropServices.Guid("c4815219-c5fd-3e96-9b86-fd6a36eef464")]
public abstract class DkmRuntimeBreakpoint : Microsoft.VisualStudio.Debugger.DkmDataContainer, IDisposable
[<System.Runtime.InteropServices.Guid("c4815219-c5fd-3e96-9b86-fd6a36eef464")>]
type DkmRuntimeBreakpoint = class
    inherit DkmDataContainer
    interface IDisposable
Public MustInherit Class DkmRuntimeBreakpoint
Inherits DkmDataContainer
Implements IDisposable
Inheritance
MarshalByRefObject
DkmDataContainer
DkmRuntimeBreakpoint
Derived
Attributes
GuidAttribute
Implements
IDisposable

Properties

IsUnloaded

Returns true if a 'unloaded' event has been raised for this object (example: DkmThread::Unload is called) or if the object has been closed. Note that care must be used when checking this status as, without synchronization, the returned status may no longer be accurate the instruction after it is read.

(Inherited from DkmDataContainer)
Process

DkmProcess represents a target process which is being debugged. The debugger debugs processes, so this is the basic unit of debugging. A DkmProcess can represent a system process or a virtual process such as minidumps.
RuntimeInstance

The DkmRuntimeInstance class represents an execution environment which is loaded into a DkmProcess and which contains code to be debugged.
SourceId

Identifies the source of an object. SourceIds are used to enable filtering in scenarios when multiple components may be creating instances of a class. For example, source ids can be used to determine if a breakpoint comes from the AD7 AL (ex: user breakpoint, or other breakpoint visible at the SDM level) instead of a breakpoint which may be created by another component (for example an internal breakpoint used for stepping).
TagValue

DkmRuntimeBreakpoint is an abstract base class. This enum indicates which derived class this object is an instance of.
Thread

[Optional] Thread on which this breakpoint should fire. If null, the breakpoint will fire on all threads.
UniqueId

Guid which uniquely identifies this pending breakpoint object.

Methods

ClearConditions()

Clear any compiled/evaluation condition associated with the specified DkmRuntimeBreakpoint. This method is implicitly called when the DkmRuntimeBreakpoint is closed.
ClearConditions(DkmWorkList, DkmCompletionRoutine<DkmClearRuntimeBreakpointConditionsAsyncResult>)

Clear any compiled/evaluation condition associated with the specified DkmRuntimeBreakpoint. This method is implicitly called when the DkmRuntimeBreakpoint is closed.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
ClearHitCountCondition(DkmBreakpointHitCountCondition, Int32)

Clears the hit count condition on a breakpoint.
ClearHitCountCondition(DkmWorkList, DkmBreakpointHitCountCondition, DkmCompletionRoutine<DkmClearRuntimeBreakpointHitCountConditionAsyncResult>)

Clears the hit count condition on a breakpoint.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
Close()

Closes the breakpoint object instance. This will release any resources associated with this object across all components. If the breakpoint is currently enabled, it will be implicitly disabled.

DkmRuntimeBreakpoint objects are automatically closed when their associated DkmRuntimeInstance object is closed.

This method may only be called by the component which created the object.
Disable()

Disables a breakpoint. Disabling a breakpoint is typically implemented by modifying the state of the target process so the breakpoint will no longer fire. For example, removing a previously inserted 'int3' from the instruction stream. If the breakpoint is already disabled, this operation has no effect. In addition to this method, a breakpoint is implicitly disabled when it is closed.

If multiple breakpoints are set on the same instruction, disabling one breakpoint does not affect the other breakpoints set on this instruction.

This method may only be called by the component which created the object.
Disable(DkmWorkList, DkmCompletionRoutine<DkmDisableRuntimeBreakpointAsyncResult>)

Disables a breakpoint. Disabling a breakpoint is typically implemented by modifying the state of the target process so the breakpoint will no longer fire. For example, removing a previously inserted 'int3' from the instruction stream. If the breakpoint is already disabled, this operation has no effect. In addition to this method, a breakpoint is implicitly disabled when it is closed.

If multiple breakpoints are set on the same instruction, disabling one breakpoint does not affect the other breakpoints set on this instruction.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.

This method may only be called by the component which created the object.
Enable()

Enables a breakpoint. Breakpoints start off initially disabled, so this method must be called before the breakpoint can be set. Enabling a breakpoint is typically implemented in the debug monitor by modifying the state of the target process. For example inserting an 'int3' instruction into the code stream. If the breakpoint is already enabled, this operation has no effect.

Once a breakpoint has been enabled, the debug monitor will raise a RuntimeBreakpoint event for this DkmRuntimeBreakpoint object whenever the trigger condition (ex: target instruction is executed) is met. Multiple DkmRuntimeBreakpoints may be set on the same instruction. In this case, the debug monitor will raise a different RuntimeBreakpoint event for each breakpoint object. Similarly, if a step complete and a breakpoint both complete on the same instruction, the debug monitor will raise both events.

This method may only be called by the component which created the object.
Enable(DkmWorkList, DkmCompletionRoutine<DkmEnableRuntimeBreakpointAsyncResult>)

Enables a breakpoint. Breakpoints start off initially disabled, so this method must be called before the breakpoint can be set. Enabling a breakpoint is typically implemented in the debug monitor by modifying the state of the target process. For example inserting an 'int3' instruction into the code stream. If the breakpoint is already enabled, this operation has no effect.

Once a breakpoint has been enabled, the debug monitor will raise a RuntimeBreakpoint event for this DkmRuntimeBreakpoint object whenever the trigger condition (ex: target instruction is executed) is met. Multiple DkmRuntimeBreakpoints may be set on the same instruction. In this case, the debug monitor will raise a different RuntimeBreakpoint event for each breakpoint object. Similarly, if a step complete and a breakpoint both complete on the same instruction, the debug monitor will raise both events.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.

This method may only be called by the component which created the object.
EvaluateConditionAndSelectThread(DkmThread)

The base debug monitor asks the breakpoint condition processor to evaluate on all stopped threads, and selects the thread whose condition is true.

Location constraint: API must be called from a Monitor component (component level < 100,000).

This API was introduced in Visual Studio 11 Update 1 (DkmApiVersion.VS11FeaturePack1).
EvaluateConditionAndSelectThread(DkmWorkList, DkmThread, DkmCompletionRoutine<DkmEvaluateConditionAndSelectThreadAsyncResult>)

The base debug monitor asks the breakpoint condition processor to evaluate on all stopped threads, and selects the thread whose condition is true.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.

Location constraint: API must be called from a Monitor component (component level < 100,000).

This API was introduced in Visual Studio 11 Update 1 (DkmApiVersion.VS11FeaturePack1).
GetCompiledCondition(DkmInstructionAddress, DkmBreakpointConditionOperator)

Call back invoked from the breakpoint condition processor to the breakpoint manager (or other component which calls SetCompiledConditionPending) when the breakpoint condition needs to be re-compiled for a new instruction address.

Location constraint: API must be called from a Monitor component (component level < 100,000).
GetDataItem<T>()

Gets the instance of 'T' which has been added to this container instance. If this container does not contain a 'T', this function will return null.

(Inherited from DkmDataContainer)
GetHitCountConditionStatus(DkmWorkList, DkmCompletionRoutine<DkmGetRuntimeBreakpointHitCountConditionAsyncResult>)

Obtains the current hit count value for a DkmRuntimeBreakpoint which has a hit count condition. This function will fail if the DkmRuntimeBreakpoint does not currently have a hit count condition.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
GetHitCountConditionStatus(Int32)

Obtains the current hit count value for a DkmRuntimeBreakpoint which has a hit count condition. This function will fail if the DkmRuntimeBreakpoint does not currently have a hit count condition.
OnBreakpointConditionFailed(DkmILFailureReason)

Call back invoked from the breakpoint condition processor to the breakpoint manager when a breakpoint condition encounters a runtime error.

Location constraint: API must be called from a Monitor component (component level < 100,000).

This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).
OnBreakpointConditionFailed(DkmThread, String, DkmILFailureReason)

Raise a RuntimeBreakpointConditionFailed event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller.

This API was introduced in Visual Studio 16 Update 3 (DkmApiVersion.VS16Update3).
OnBreakpointConditionFailed(String)

Call back invoked from the breakpoint condition processor to the breakpoint manager when a breakpoint condition encounters a runtime error.

Location constraint: API must be called from a Monitor component (component level < 100,000).
OnDataBreakpointHit(DkmThread, Boolean, String)

Raise a RuntimeDataBreakpointHit event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller.

This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM).
OnError(DkmBreakpointMessageLevel, String)

This method will be called when an breakpoint has been invalid and needs to inform the UI.

Location constraint: This can be called from any component.

This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM).
OnHit(DkmThread, Boolean)

Raise a RuntimeBreakpoint event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller.
OnHitWithError(DkmThread, Boolean, DkmBreakpointMessageLevel, String)

Raise a RuntimeBreakpointHitWithError event. Components which implement the event sink interface will receive the event notification. This method will enqueue the event and control will immediately return to the caller.

This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM).
RemoveDataItem<T>()

Remove the instance of 'T' from this container. It is usually unnecessary to call this method as a data container will automatically be emptied when the object is closed.

(Inherited from DkmDataContainer)
RequestBreakpointEventOnModifiedThread(DkmThread)

The breakpoint condition processor decides not to break on the given thread but another thread of the same warp, so the breakpoint condition processor instructs the base debug monitor to re-send the breakpoint event on the other thread.
RequestBreakpointEventOnModifiedThread(DkmWorkList, DkmThread, DkmCompletionRoutine<DkmRequestBreakpointEventOnModifiedThreadAsyncResult>)

The breakpoint condition processor decides not to break on the given thread but another thread of the same warp, so the breakpoint condition processor instructs the base debug monitor to re-send the breakpoint event on the other thread.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
SetCompiledConditionPending()

This method is similar to SetCompiledCondition, but is used in cases where the instruction address is not known up front, such as data breakpoints. In these cases, when the breakpoint is first hit at a particular address, a call will be made to the breakpoint client to obtain a new compiled condition for this address (IDkmBreakpointConditionProcessorClient.GetCompiledCondition). This is used for languages which are evaluated in the IDE process (ex: C++).
SetCompiledConditionPending(DkmWorkList, DkmCompletionRoutine<DkmSetCompiledConditionPendingAsyncResult>)

This method is similar to SetCompiledCondition, but is used in cases where the instruction address is not known up front, such as data breakpoints. In these cases, when the breakpoint is first hit at a particular address, a call will be made to the breakpoint client to obtain a new compiled condition for this address (IDkmBreakpointConditionProcessorClient.GetCompiledCondition). This is used for languages which are evaluated in the IDE process (ex: C++).

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
SetDataItem<T>(DkmDataCreationDisposition, T)

Place a new item in the data container.

(Inherited from DkmDataContainer)
SetEvaluationCondition(DkmBreakpointCondition, String)

Sets a breakpoint condition which is evaluated on the target computer. This is used for .NET languages.
SetEvaluationCondition(DkmWorkList, DkmBreakpointCondition, DkmCompletionRoutine<DkmSetEvaluationConditionAsyncResult>)

Sets a breakpoint condition which is evaluated on the target computer. This is used for .NET languages.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
SetHitCountCondition(DkmBreakpointHitCountCondition, Int32)

Initialize or update the hit count condition/value on a breakpoint. If the same breakpoint has both a language-level condition, and a hit count condition, the language-level condition is applied first. The condition is implicitly removed if the DkmRuntimeBreakpoint is closed.
SetHitCountCondition(DkmWorkList, DkmBreakpointHitCountCondition, Int32, DkmCompletionRoutine<DkmSetRuntimeBreakpointHitCountConditionAsyncResult>)

Initialize or update the hit count condition/value on a breakpoint. If the same breakpoint has both a language-level condition, and a hit count condition, the language-level condition is applied first. The condition is implicitly removed if the DkmRuntimeBreakpoint is closed.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.
Test()

Determines if the given DkmRuntimeBreakpoint could be enabled. This is used from within the breakpoints dialog to validate breakpoints before the dialog is closed.
Test(DkmWorkList, DkmCompletionRoutine<DkmTestRuntimeBreakpointAsyncResult>)

Determines if the given DkmRuntimeBreakpoint could be enabled. This is used from within the breakpoints dialog to validate breakpoints before the dialog is closed.

This method will append a new work item to the specified work list, and return once the work item has been appended. The actual processing of the work item is asynchronous. The caller will be notified that the request is complete through the completion routine.

Explicit Interface Implementations

IDisposable.Dispose()

To be added.

Applies to