DkmRuntimeInstance Class

Definition

Namespace:

Microsoft.VisualStudio.Debugger

Assembly:

Microsoft.VisualStudio.Debugger.Engine.dll

Package:

Microsoft.VisualStudio.Debugger.Engine v17.8.1101801

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

Derived classes: DkmClrRuntimeInstance, DkmClrNcRuntimeInstance, DkmCustomRuntimeInstance, DkmNativeRuntimeInstance, DkmScriptRuntimeInstance, DkmNativeDwarfRuntimeInstance, DkmOpenEnclaveRuntimeInstance

public ref class DkmRuntimeInstance abstract : Microsoft::VisualStudio::Debugger::DkmDataContainer

[System.Runtime.InteropServices.Guid("9b32a175-6e35-1ae5-1498-c93ab323e2c8")]
public abstract class DkmRuntimeInstance : Microsoft.VisualStudio.Debugger.DkmDataContainer

[<System.Runtime.InteropServices.Guid("9b32a175-6e35-1ae5-1498-c93ab323e2c8")>]
type DkmRuntimeInstance = class
    inherit DkmDataContainer

Public MustInherit Class DkmRuntimeInstance
Inherits DkmDataContainer

Inheritance

Object

DkmDataContainer

DkmRuntimeInstance

Derived

Microsoft.VisualStudio.Debugger.Clr.DkmClrRuntimeInstance

Microsoft.VisualStudio.Debugger.CustomRuntimes.DkmCustomRuntimeInstance

Microsoft.VisualStudio.Debugger.Native.DkmNativeDwarfRuntimeInstance

Microsoft.VisualStudio.Debugger.Native.DkmNativeRuntimeInstance

Microsoft.VisualStudio.Debugger.Native.DkmOpenEnclaveRuntimeInstance

Microsoft.VisualStudio.Debugger.Script.DkmScriptRuntimeInstance

Attributes

GuidAttribute

Properties

Capabilities	Enumeration of runtime capabilities. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
Connection	This represents a connection between the monitor and the IDE. It can either be a local connection if the monitor is running in the same process as the IDE, or it can be a remote connection. In the monitor process, there is only one connection.
Id	Identifies a DkmRuntimeInstance object within a process.
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)
ParentRuntime	[Optional] For runtimes that are implemented on top of another runtime, this can optionally be used to indicant the logical parent. This can then be used to request services from the parent when the child runtime doesn't implement the service. This is currently used only for obtaining the top stack frame to evaluate a conditional breakpoint when the child runtime doesn't walk stacks itself. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
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.
TagValue	DkmRuntimeInstance is an abstract base class. This enum indicates which derived class this object is an instance of.

Methods

AfterSteppingArbitration(DkmStepper, DkmStepArbitrationReason, DkmRuntimeInstance)	AfterSteppingArbitration is called by the stepping manager on the old controlling runtime instance after stepping arbitration is complete but before the next runtime instance starts stepping. This allows runtimes to clear any stepping state if another runtime took control. If no other runtime monitor claimed the current location, the original monitor should finish the step. This is indicated by NewControllingRuntimeInstance being null. For instance, a runtime instance may choose to step back out if a step-in landed in a location without symbols and no other runtime took control. Location constraint: API must be called from a Monitor component (component level < 100,000).
BeforeEnableNewStepper(DkmStepper)	BeforeEnableNewStepper is called by the stepping manager before a new stepper is enabled. This gives runtimes the ability to do any initialization that might be required such as performing pre-step function evaluations. Location constraint: API must be called from a Monitor component (component level < 100,000).
Disassemble(DkmInstructionAddress, UInt32)	Disassemble an address range in the debuggee runtime. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
FindModulesByName(String)	This method returns all modules that match the specified name.
GetCodePathsInRange(ICorDebugFrame, UInt32, UInt32)	GetCodePathsInRange is called to get code paths in specific IL range. Location constraint: It should only be called on server side. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
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)
GetInstructionAddress(DkmInstructionAddress, Int32)	Returns the address of the kth instruction relative to a starting address. For constant length instruction sets, this is simple arithmetic. For variable length instruction sets, reverse-disassembly is required to obtain this address. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
GetManagedHeapSamplers()	GetManagedHeapSamplers enumerates the DkmManagedHeapSampler elements of this DkmRuntimeInstance object. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
GetManagedHeapWalkers()	GetManagedHeapWalkers enumerates the DkmManagedHeapWalker elements of this DkmRuntimeInstance object. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
GetModuleInstances()	GetModuleInstances enumerates the DkmModuleInstance elements of this DkmRuntimeInstance object.
GetScriptDocumentTreeNodes()	GetScriptDocumentTreeNodes enumerates the DkmScriptDocumentTreeNode elements of this DkmRuntimeInstance object.
GetSymbolNameForAddress(DkmWorkList, UInt64, DkmCompletionRoutine<DkmGetSymbolNameForAddressAsyncResult>)	Gets the symbol name for the specified address using runtime information instead of symbols. Currently this is just implemented for the CLR runtime instance. 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 an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 Update 7 (DkmApiVersion.VS16Update7).
GetTaskProviders()	GetTaskProviders enumerates the DkmTaskProvider elements of this DkmRuntimeInstance object.
GetThreadDisplayProperties(DkmWorkList, DkmThread, DkmCompletionRoutine<DkmGetThreadDisplayPropertiesAsyncResult>)	Gets the Display Properties of the Thread including the Display Name and Thread Category. 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 an IDE component (component level > 100,000).
GetThreadName(DkmThread)	Compute the name of a thread.
GetThreadName(DkmWorkList, DkmThread, DkmCompletionRoutine<DkmGetThreadNameAsyncResult>)	Compute the name of a 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.
NotifyStepComplete(DkmStepper)	NotifyStepComplete is called by the stepping manager on all non-controlling runtime instances when a step is complete. Location constraint: API must be called from a Monitor component (component level < 100,000).
OnLoadComplete()	This method is called by a debug monitor to raise a RuntimeInstanceLoadComplete event. RuntimeInstanceLoadComplete is currently only sent for the native runtime instance, though this may change in the future. The event is issued after DkmModuleInstance objects have been created for the initial set of modules in the runtime instance. This method may only be called by the component which created the object. This API was introduced in Visual Studio 12 Update 2 (DkmApiVersion.VS12Update2).
OnNewControllingRuntimeInstance(DkmStepper, DkmStepArbitrationReason, DkmRuntimeInstance)	OnNewControllingRuntimeInstance is called by the stepping manager on all non-controlling runtime instances after step arbitration has selected a new controlling runtime instance. Location constraint: API must be called from a Monitor component (component level < 100,000).
OwnsCurrentExecutionLocation(DkmStepper, DkmStepArbitrationReason)	OwnsCurrentExecutionLocation is called by the stepping manager while it is searching for monitors to perform a step. If the current location in the debuggee is understood by this monitor it can return true here to take control of the step. Location constraint: API must be called from a Monitor component (component level < 100,000).
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)
ResolveCPUInstructionAddress(DkmWorkList, UInt64, DkmCompletionRoutine<DkmResolveCPUInstructionAddressAsyncResult>)	Resolves a CPU InstructionAddress to a runtime-specific DkmInstructionAddress object. This API is currently only supported by CLR DkmRuntimeInstance objects, and the CLR runtime instance can currently only find instruction addresses which are in a method that is currently on the call stack of one of the threads in the target process. 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: This API should generally be called on the client, but it can be called on the server for translating CLR addresses (but not native-compiled).
ResolveCPUInstructionAddress(UInt64, Boolean)	Resolves a CPU InstructionAddress to a runtime-specific DkmInstructionAddress object. This API is currently only supported by CLR DkmRuntimeInstance objects, and the CLR runtime instance can currently only find instruction addresses which are in a method that is currently on the call stack of one of the threads in the target process. Location constraint: This API should generally be called on the client, but it can be called on the server for translating CLR addresses (but not native-compiled).
SetDataItem<T>(DkmDataCreationDisposition, T)	Place a new item in the data container. (Inherited from DkmDataContainer)
SetRegisterValue(DkmStackWalkFrame, Int32, ReadOnlyCollection<Byte>)	Sets the value of the register in the thread's context. Sub registers that are made up of larger registers are supported.
Step(DkmStepper, DkmStepArbitrationReason)	Step is called by the stepping manager after it determines this monitor is the correct monitor to perform the step. Location constraint: API must be called from a Monitor component (component level < 100,000).
StepControlRequested(DkmStepper, DkmStepArbitrationReason, DkmRuntimeInstance)	StepControlRequested is called by the stepping manager when a non-controlling runtime instance detects that the thread has hit a transition into its runtime. 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).
StopStep(DkmStepper)	StopStep is called by the stepping manager when the process is being continued to clear out any remaining stepping state for a stepper. Location constraint: API must be called from a Monitor component (component level < 100,000).
TakeStepControl(DkmStepper, Boolean, DkmStepArbitrationReason, DkmRuntimeInstance)	TakeStepControl is called by the stepping manager 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).
Unload()	RuntimeInstanceUnload is sent by the dispatcher when DkmRuntimeInstance::Unload is invoked by the monitor. This method may only be called by the component which created the object.