DkmScriptRuntimeInstance Class

Definition

Represents a script-based execution environment executing in a target process.

public ref class DkmScriptRuntimeInstance : Microsoft::VisualStudio::Debugger::DkmRuntimeInstance
[System.Runtime.InteropServices.Guid("f6cb156c-9ad9-c01d-29e0-cb77e45fa254")]
public class DkmScriptRuntimeInstance : Microsoft.VisualStudio.Debugger.DkmRuntimeInstance
[<System.Runtime.InteropServices.Guid("f6cb156c-9ad9-c01d-29e0-cb77e45fa254")>]
type DkmScriptRuntimeInstance = class
    inherit DkmRuntimeInstance
Public Class DkmScriptRuntimeInstance
Inherits DkmRuntimeInstance
Inheritance
Inheritance
DkmScriptRuntimeInstance
Attributes

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)
Id

Identifies a DkmRuntimeInstance object within a process.

(Inherited from DkmRuntimeInstance)
IsEdgeHtmlDll

A flag indicating whether the current loaded dll is EdgeHtml.dll or not.

This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).

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)
LoadOrderIndex

Index indicating the relative load order of this script runtime instance to other script runtime instances within the target process. The first runtime instance to load will be given an index of zero.

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)
ScriptHostVersion

File version of the script host dll. This will be 0 if it cannot be obtained. The top 16 bits are the major version, followed by 16 bits for the minor version, followed by 16 bits for the build number followed by 16 bits for the build revision.

This API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).

TagValue

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

(Inherited from DkmRuntimeInstance)

Methods

AbortExecutionOnResume()

API which is called from break mode which tells the script runtime that execution should be aborted when resuming (BREAKRESUMEACTION_ABORT). This API requires an MSHTML v10+ target execution environment.

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)
Create(DkmProcess, DkmRuntimeInstanceId, DkmRuntimeCapabilities, DkmRuntimeInstance, Int32, Boolean, UInt64, 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 14 RTM (DkmApiVersion.VS14RTM).

Create(DkmProcess, DkmRuntimeInstanceId, DkmRuntimeCapabilities, DkmRuntimeInstance, Int32, 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, Int32, 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)
FindModulesByName(String)

This method returns all modules that match the specified name.

(Inherited from DkmRuntimeInstance)
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)
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).

(Inherited from DkmRuntimeInstance)
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)
GetModuleInstances()

GetModuleInstances enumerates the DkmModuleInstance elements of this DkmRuntimeInstance object.

(Inherited from DkmRuntimeInstance)
GetRemoteDebugApplication()

Allows a caller to obtain a direct access to the IRemoteDebugApplication interface from the target process. This can be used to load dlls into the target application, or inspect the target application. Note that this should never be used for execution control, breakpoints, or evaluation.

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

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)
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)
OnScriptCriticalError(DkmWorkList, String, Int32, String, DkmScriptInstructionAddress, DkmSourcePosition, DkmCompletionRoutine<DkmOnScriptCriticalErrorAsyncResult>)

Provides notification to the user that a critical error has happened in the target process. This method will complete once the critical error UI has been dismissed.

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).

OnScriptSymbolsUpdated(DkmScriptDocument[])

Raises the notification that one or more script documents have been updated.

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)
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)

Applies to