DkmStepper Class

Reference

Definition

Namespace:: Microsoft.VisualStudio.Debugger.Stepping

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

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

DkmStepper represents a request to step a thread. It facilitates shared object lifetime between the various runtime debug monitors that participate in stepping.

public ref class DkmStepper : Microsoft::VisualStudio::Debugger::DkmDataContainer, IDisposable

[System.Runtime.InteropServices.Guid("2aae9764-33a3-8fc7-22ff-e27c9de91bda")]
public class DkmStepper : Microsoft.VisualStudio.Debugger.DkmDataContainer, IDisposable

[<System.Runtime.InteropServices.Guid("2aae9764-33a3-8fc7-22ff-e27c9de91bda")>]
type DkmStepper = class
    inherit DkmDataContainer
    interface IDisposable

Public Class DkmStepper
Inherits DkmDataContainer
Implements IDisposable

Inheritance: MarshalByRefObject

DkmDataContainer
DkmStepper

Attributes: GuidAttribute

Implements: IDisposable

Properties

CodePath	[Optional] If StepKind is StepIntoSpecific, specifies which call we are stepping into. Otherwise it is NULL.
CrossThreadParent	[Optional] If a new stepper is created using OnCrossThreadStepArbitration, the stepping manager will set this field to make is easy to get back to the original stepper if the cross thread step fails or needs to fallback.
CurrentCodePaths	[Optional] In managed debugging, it contains all code paths in current step range. Otherwise it is NULL. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
CurrentMethodName	[Optional] In managed debugging, it contains current method name. Otherwise it is NULL. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
FrameBase	The frame base of the first frame at the beginning of the step. This value will be MAXUINT64 if the StartingAddress was not specified.
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)
ShouldCaptureReturnValue	In managed debugging, it indicates if the stepper wanted to capture return value during stepping. Default it is false. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
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).
StartingAddress	[Optional] The instruction address of the process at the time this step started. This will be NULL if the step originated on a thread with no frames (Script & Managed Only).
StepKind	DkmStepKind describes how to step the thread when the Step Method is called.
StepUnit	DkmStepUnit describes the granularity of the step when the Step method is called.
Thread	DkmThread represents a thread running in the target process.
UniqueId	Guid which uniquely identifies this DkmStepper.

Methods

BeforeEnable()	Called by the stopping event manager before a step operation actually begins The stopping event manager will notify all runtime instances so they can setup any necessary state before the the stopping event manager starts blocking function evaluations. Location constraint: API must be called from a Monitor component (component level < 100,000).
CancelStepper(DkmRuntimeInstance)	Allows a stepper to be cancelled after creation by the controlling runtime instance. The calling runtime instance must match the current controlling runtime instance. This is generally used in cross thread stepping scenarios where the original stepper may be reactivated. The stepping manager will close the stepper and not send step complete. Location constraint: API must be called from a Monitor component (component level < 100,000).
Close()	Closes the stepper object. This should be closed by components when the stepper is done, such as when a step complete event is suppressed, or if the stepper fails to initialize. Steppers will be implicitly closed if their thread exits, or the debugger is stopped. They will be closed by the stepping manager if a different user-level execution request is issued. DkmStepper objects are automatically closed when their associated DkmThread object is closed.
Create(DkmThread, DkmInstructionAddress, UInt64, DkmStepKind, DkmStepUnit, Guid, DkmSteppingCodePath, DkmStepper, Boolean, ReadOnlyCollection<DkmSteppingCodePath>, String, DkmDataItem)	DkmStepper objects are created by components that wish to issue a step. User-level steppers are created by the AD7-AL. To initialize a stepper object, Enable must be called. Stepper objects will live until the step completes, or is aborted. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
Create(DkmThread, DkmInstructionAddress, UInt64, DkmStepKind, DkmStepUnit, Guid, DkmSteppingCodePath, DkmStepper, DkmDataItem)	DkmStepper objects are created by components that wish to issue a step. User-level steppers are created by the AD7-AL. To initialize a stepper object, Enable must be called. Stepper objects will live until the step completes, or is aborted.
Enable(Boolean)	Used to initialize a stepper object so that the step will be performed when execution is next resumed. This method is implemented by the stepping manager by finding an appropriate runtime debug monitor, and asking this runtime debug monitor to setup a step. This method should only be called once for a given stepper object. Location constraint: API must be called from a Monitor component (component level < 100,000).
GetControllingRuntimeInstance()	Returns the runtime instance currently in-control of this DkmStepper. Location constraint: API must be called from a Monitor component (component level < 100,000).
GetCrossThreadParent()
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)
IsExceptionInFlight()	Gets the flag on the DkmStepper that states if a runtime monitor believes an exception is currently in flight during this step. This can be used by runtime monitors to change the behavior of stepping. 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).
OnCrossThreadStepArbitration(DkmStepArbitrationReason, DkmRuntimeInstance, DkmThread, DkmInstructionAddress, DkmStepper)	Called by a runtime monitor when a step is continuing on a different thread. The stepping manager will create a new DkmStepper to be used on the new thread and initiate stepping arbitration to determine which runtime should complete the step just as OnStepArbitration does. The new stepper uses the same step kind and step unit as the original stepper. A new starting instruction address must be given and is set as the stepper's starting address. The original stepper remains alive and when the new stepper completes the stepping manager will suppress the event and notify the original stepper of the completion. Location constraint: API must be called from a Monitor component (component level < 100,000).
OnReturnValues(ReadOnlyCollection<DkmRawReturnValue>, Boolean)	Raise a ReturnValues event. Components which implement the event sink interface will receive the event notification. Control will return once all components have been notified.
OnStepArbitration(DkmStepArbitrationReason, DkmRuntimeInstance)	Called by a runtime monitor when a step has left the confines of what the runtime monitor understands or a potential transition into another runtime has been encountered during a step. The stepping manager will initiate stepping arbitration to give each runtime monitor a chance to inspect the process and determine which runtime should complete the step. The runtimes are called in priority order. After this process is complete, the stepping manager will call AfterSteppingArbitration on the monitor that requested arbitration so it can respond to the new controlling monitor if one was found, or finish the step if one was not found. Location constraint: API must be called from a Monitor component (component level < 100,000).
OnStepComplete(DkmThread, Boolean)	Raise a StepComplete 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.
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)
SetDataItem<T>(DkmDataCreationDisposition, T)	Place a new item in the data container. (Inherited from DkmDataContainer)
SetExceptionInFlight(Boolean)	Runtime monitors call this to set or clear a flag on the DkmStepper that can be used by cooperating runtimes to change the behavior of stepping if an exception is current in flight. Called by runtime monitors when an exception is encountered while stepping. 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).
StepControlRequested(DkmStepArbitrationReason, DkmRuntimeInstance)	StepControlRequested is called when a non-controlling runtime instance detects that the thread has hit a transition into its runtime. The stepping manager will forward the call to the current controlling runtime instance. If the current controlling runtime instance can stop stepping, it should set Granted to true. Actual control is not given until the requesting runtime calls DkmStepper.TakeStepControl. This two part process allows callers to request control of multiple steppers at the same time. Location constraint: API must be called from a Monitor component (component level < 100,000).
TakeStepControl(Boolean, DkmStepArbitrationReason, DkmRuntimeInstance)	TakeStepControl is called when a non-controlling runtime instance detects that the thread has hit a transition into its runtime. The stepping manager will forward the call to the current controlling runtime instance. The runtime instance requesting control should first call StepControlRequested on all steppers it wants control of. If they all set Granted to true, the runtime instance should then call this method on each stepper it is taking control of. Location constraint: API must be called from a Monitor component (component level < 100,000).

Explicit Interface Implementations

IDisposable.Dispose()

To be added.

Applies to