DkmClrRuntimeInstance Class

Definition

Namespace:

Microsoft.VisualStudio.Debugger.Clr

Assembly:

Microsoft.VisualStudio.Debugger.Engine.dll

Represents a CLR instance running in a target process.

Derived classes: DkmClrNcRuntimeInstance

public ref class DkmClrRuntimeInstance : Microsoft::VisualStudio::Debugger::DkmRuntimeInstance

[System.Runtime.InteropServices.Guid("ea234770-c86f-1706-8842-c6fb5311ba79")]
public class DkmClrRuntimeInstance : Microsoft.VisualStudio.Debugger.DkmRuntimeInstance

[<System.Runtime.InteropServices.Guid("ea234770-c86f-1706-8842-c6fb5311ba79")>]
type DkmClrRuntimeInstance = class
    inherit DkmRuntimeInstance

Public Class DkmClrRuntimeInstance
Inherits DkmRuntimeInstance

Inheritance

MarshalByRefObject

DkmDataContainer

DkmRuntimeInstance

DkmClrRuntimeInstance

Derived

Microsoft.VisualStudio.Debugger.Clr.NativeCompilation.DkmClrNcRuntimeInstance

Attributes

GuidAttribute

Properties

Capabilities	Enumeration of runtime capabilities. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM). (Inherited from DkmRuntimeInstance)
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. (Inherited from DkmRuntimeInstance)
CORSystemDirectory	[Optional] The installation directory of the common language runtime (CLR) instance. For example 'c:\Windows\Microsoft.NET\Framework\v2.0.50727'. This is the same path returned from the GetCORSystemDirectory API, and it always includes the trailing slash.
Id	Identifies a DkmRuntimeInstance object within a process. (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
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. (Inherited from DkmRuntimeInstance)
RuntimeVersion	[Optional] The version string for the CLR instance (ex: 'v2.0.50727').
TagValue	DkmRuntimeInstance is an abstract base class. This enum indicates which derived class this object is an instance of. (Inherited from DkmRuntimeInstance)

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). (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
CanDoFuncEval(DkmThread)	Checks if the given thread is in a state in which the CLR supports managed func-evals. Location constraint: API must be called from a Monitor component (component level < 100,000).
ContinueForFuncEval(DkmThread, ICorDebugEval, DkmFuncEvalFlags, UInt32, String)	Continue the process and wait for a func-eval to complete. The caller should always execute 'CanDoFuncEval' before creating the ICorDebugEval and setting up the evaluation. Location constraint: API must be called from a Monitor component (component level < 100,000).
ContinueForFuncEval(DkmThread, ICorDebugEval, DkmFuncEvalFlags, UInt32, String, DkmClrInstructionAddress)	Continue the process and wait for a func-eval to complete. The caller should always execute 'CanDoFuncEval' before creating the ICorDebugEval and setting up the evaluation. Location constraint: API must be called from a Monitor component (component level < 100,000). This API was introduced in Visual Studio 15 RTM (DkmApiVersion.VS15RTM).
Create(DkmProcess, DkmRuntimeInstanceId, DkmRuntimeCapabilities, DkmRuntimeInstance, String, String, DkmDataItem)	Creates a new runtime instance object from a debug monitor. This method must be called from the event thread when a debug monitor detects that a new runtime instance has loaded (for example, when the corresponding runtime dll loads in the target process). This method will send a RuntimeInstanceLoad event. Location constraint: API must be called from a Monitor component (component level < 100,000). This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).
Create(DkmProcess, DkmRuntimeInstanceId, String, String, DkmDataItem)	Creates a new runtime instance object from a debug monitor. This method must be called from the event thread when a debug monitor detects that a new runtime instance has loaded (for example, when the corresponding runtime dll loads in the target process). This method will send a RuntimeInstanceLoad event. 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). (Inherited from DkmRuntimeInstance)
FindAppDomain(Int32)	Find a DkmClrAppDomain element within this DkmClrRuntimeInstance. If no element with the given input key is present, FindAppDomain will fail.
FindClrModuleInstance(ICorDebugModule)	Obtains the DkmClrModuleInstance from an ICorDebugModule. Location constraint: API must be called from a Monitor component (component level < 100,000).
FindModulesByName(String)	This method returns all modules that match the specified name. (Inherited from DkmRuntimeInstance)
GetActiveStatements(DkmActiveStatement[])	Provides the stack of all active statements across all threads. So if the same function is on a call stack multiple times, it will be duplicated in this array. Entries in the stack are grouped by thread. Location constraint: Can be called from client to server side. This API was introduced in Visual Studio 15 Update 5 (DkmApiVersion.VS15Update5).
GetActiveStatements(DkmWorkList, DkmCompletionRoutine<DkmGetActiveStatementsAsyncResult>)	Provides the stack of all active statements across all threads. So if the same function is on a call stack multiple times, it will be duplicated in this array. Entries in the stack are grouped by 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. Location constraint: Can be called from client to server side. This API was introduced in Visual Studio 15 Update 5 (DkmApiVersion.VS15Update5).
GetAliases(DkmInspectionContext)	Gets the list of aliases that can currently be used in expressions. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).
GetAppDomains()	GetAppDomains enumerates the DkmClrAppDomain elements of this DkmClrRuntimeInstance object.
GetApplyUpdateCapabilities()
GetApplyUpdateCapabilities(DkmWorkList, DkmCompletionRoutine<DkmGetApplyUpdateCapabilitiesAsyncResult>)
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). (Inherited from DkmRuntimeInstance)
GetCorFrame(DkmThread, UInt64, Guid)	GetCorFrame is used to obtain a ICorDebugFrame which a component can use to deeply inspect the stack frame. The returned interface may ONLY be used to inspect the target process, and should NEVER be used to control execution (no stepping, no breakpoints, no continue, etc). Doing so is unsupported and will result in undefined behavior. Location constraint: This API must be called from the same process where the target runtime implements stack walk. For managed debugging, this means that when debugging 64-bit or remote processes, this API must be called from a debug monitor component. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).
GetCorProcess()	Provides direct access to the ICorDebugProcess object, which expression evaluators or other components can use for inspection. The returned interface may ONLY be used to inspect the target process, and should NEVER be used to control execution (no stepping, no breakpoints, no continue, etc). Doing so is unsupported and will result in undefined behavior. Location constraint: API must be called from a Monitor component (component level < 100,000).
GetCorThread(DkmThread)	Provides direct access to the ICorDebugThread object, which expression evaluators or other components can use to inspect the app domain. The returned interface may ONLY be used to inspect the target process, and should NEVER be used to control execution (no stepping, no breakpoints, no continue, etc). Doing so is unsupported and will result in undefined behavior. 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)
GetEncAvailability(String)	Checks whether Edit and Continue is supported for the corresponding runtime instance. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 Update 1 (DkmApiVersion.VS16Update1).
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). (Inherited from DkmRuntimeInstance)
GetIntrinsicAssemblyMetaDataBytesPtr(UInt32)	Get metadata for the "Intrinsic Methods Assembly". Intrinsic methods are special methods the debug engine understands when executing a CLR inspection query. Example: When evaluating "$exception" in the C# expression evaluator, the C# expression compiler will emit a call to GetException in the intrinsic methods assembly. Instead of executing the call normally, the debugger will instead simulate the method call and return the exception on the current thread. This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).
GetManagedHeapSamplers()	GetManagedHeapSamplers enumerates the DkmManagedHeapSampler elements of this DkmRuntimeInstance object. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM). (Inherited from DkmRuntimeInstance)
GetManagedHeapWalkers()	GetManagedHeapWalkers enumerates the DkmManagedHeapWalker elements of this DkmRuntimeInstance object. This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM). (Inherited from DkmRuntimeInstance)
GetMethodReturnAddresses(DkmClrModuleInstance, DkmClrMethodId)	Internal helper method for finding all ret instruction addresses in a given method. NB! The addresses point to the actual IL, not the current/previous sequence point! Location constraint: None. This API was introduced in Visual Studio 16 Update 6 (DkmApiVersion.VS16Update6).
GetModuleInstances()	GetModuleInstances enumerates the DkmModuleInstance elements of this DkmRuntimeInstance object. (Inherited from DkmRuntimeInstance)
GetOutOfProcStepAddresses(DkmStepper, DkmStackWalkFrame, DkmSteppingRange[])	Internal helper method for finding candidate addresses for step in/over. Location constraint: None. This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTMPreview).
GetScriptDocumentTreeNodes()	GetScriptDocumentTreeNodes enumerates the DkmScriptDocumentTreeNode elements of this DkmRuntimeInstance object. (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
GetTaskProviders()	GetTaskProviders enumerates the DkmTaskProvider elements of this DkmRuntimeInstance object. (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
GetThreadName(DkmThread)	Compute the name of a thread. (Inherited from DkmRuntimeInstance)
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. (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
OnFuncEvalQuickAbortDllLoaded(DkmThread, Boolean)	Notifies the result of the attempt to load the FEQA DLL. 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). (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
PrepareForFuncEvalQuickAbort(DkmThread, Boolean, UInt64)	Checks to see if we should load the FEQA DLL. 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). (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
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. (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
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). (Inherited from DkmRuntimeInstance)
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. (Inherited from DkmRuntimeInstance)