DkmClrModuleInstance Class

Definition

'DkmClrModuleInstance' is used for modules which are loaded into the Common Language Runtime.

Derived classes: DkmClrNcModuleInstance

public ref class DkmClrModuleInstance : Microsoft::VisualStudio::Debugger::DkmModuleInstance
[System.Runtime.InteropServices.Guid("29da4ffa-6063-6232-46dd-64d14cf56ddf")]
public class DkmClrModuleInstance : Microsoft.VisualStudio.Debugger.DkmModuleInstance
[<System.Runtime.InteropServices.Guid("29da4ffa-6063-6232-46dd-64d14cf56ddf")>]
type DkmClrModuleInstance = class
    inherit DkmModuleInstance
Public Class DkmClrModuleInstance
Inherits DkmModuleInstance
Inheritance
Derived
Attributes

Properties

AppDomain

DkmClrAppDomain represents a CLR app domain inside a process which is being debugged.

BaseAddress

[Optional] The starting memory address of where the module loaded. This value will be zero if the module did not load in a contiguous block of memory.

(Inherited from DkmModuleInstance)
ClrFlags

Flags which indicates traits of a DkmModuleInstance which has been loaded by the CLR.

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

Flags which indicate traits of a DkmModuleInstance.

(Inherited from DkmModuleInstance)
FullName

Fully qualified module name. For file-based modules, this is the full path to the module (ex: c:\windows\system32\kernel32.dll.

(Inherited from DkmModuleInstance)
ILImageSize

Specifies the size of the IL image of this module, as it pertains to symbol server lookup. For Desktop .NET Framework, this will specify the IL image size which will differ from the raw image size in the case of ngen. This is because the IL only image is what is indexed on Symbol Servers. For .NET Core ngen and ready to run, this will specify the raw image size as the ngen/ready to run image is what is indexed and we do not want to do lookup based on IL only image size.

This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).

IsDisabled

Indicates if this module instance has been disabled. Disabled modules are largely ignored by the debugger. For native modules, the address range of the disabled module is treated as if it is unmapped. For CLR modules, any frames from these modules is hidden from the call stack.

(Inherited from DkmModuleInstance)
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)
LoadContext

String description of the context under which this module has been loaded. ex: 'Win32' or 'CLR v2.0.50727: Default Domain'.

(Inherited from DkmModuleInstance)
LoadOrder

The integer count of the number of module instances that have loaded up to and including this module. Each runtime instance keeps track of its own load order count.

(Inherited from DkmModuleInstance)
MemoryLayout

Enumeration that indicates how a module is laid out in memory.

(Inherited from DkmModuleInstance)
MinidumpInfoPart

[Optional] 'MinidumpInfoPart' is used to convey additional information about modules in a DkmProcess for a minidump.

(Inherited from DkmModuleInstance)
Module

[Optional] The symbol handler's representation of a module (DkmModule) which is associated with this module instance. This value is initially null, and is assigned if and when symbols are associated with this module instance.

(Inherited from DkmModuleInstance)
Mvid

Module Version Identifier from the loaded module. This is a unique value which is embedded in an exe/dll by linkers/compilers when the dll/exe is built. A new value is generated each time that the dll/exe is compiled.

Name

Short representation of the module name. For file-based modules, this is the file name and extension (ex: kernel32.dll).

(Inherited from DkmModuleInstance)
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 DkmModuleInstance)
RuntimeInstance

Represents a CLR instance running in a target process.

Size

[Optional] The number of bytes in the module's memory region. This value will be zero if the module did not load in a contiguous block of memory.

(Inherited from DkmModuleInstance)
SymbolFileId

[Optional] Contains information needed to locate symbols for this module. On Win32, this information is contained within the IMAGE_DEBUG_DIRECTORY.

(Inherited from DkmModuleInstance)
TagValue

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

(Inherited from DkmModuleInstance)
TimeDateStamp

Date/Time of when the loaded module was built. This value is obtained from the IMAGE_NT_HEADERS of the loaded module. The unit of measurement is a FILETIME value, which is a 64-bit value representing the number of 100-nanosecond intervals since January 1, 1601 (UTC).

(Inherited from DkmModuleInstance)
UniqueId

Uniquely identifies the DkmModuleInstance object.

(Inherited from DkmModuleInstance)
Version

[Optional] File version information.

(Inherited from DkmModuleInstance)

Methods

ClearTransitionModuleFlag()

Runtime instances call this method to mark a module as a boundary module. When stepping, runtimes should check if the step has hit a boundary module and start stepping arbitration if they have. Note that some runtimes may not be able to honor this request. The dispatcher will keep a count of the number of times FlagAsTransitionModule has been called. Only when a matching number of calls to ClearTransitionModuleFlag will the module no longer be considered a transition module.

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

(Inherited from DkmModuleInstance)
Create(String, String, UInt64, DkmModuleVersion, DkmSymbolFileId, DkmModuleFlags, DkmModuleMemoryLayout, UInt64, UInt32, UInt32, String, DkmClrRuntimeInstance, Guid, DkmClrModuleFlags, DkmClrAppDomain, Boolean, DkmModule, DkmModuleInstance+MinidumpInfo, DkmDataItem)

Create a new DkmClrModuleInstance object instance.

This method will send a ModuleInstanceLoad event.

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

Create(String, String, UInt64, DkmModuleVersion, DkmSymbolFileId, DkmModuleFlags, DkmModuleMemoryLayout, UInt64, UInt32, UInt32, String, DkmClrRuntimeInstance, Guid, DkmClrModuleFlags, DkmClrAppDomain, UInt32, Boolean, DkmModule, DkmModuleInstance+MinidumpInfo, DkmDataItem)

Create a new DkmClrModuleInstance object instance.

This method will send a ModuleInstanceLoad 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).

Decompile()

Decompiles the code for a module into C# and creates a new portable PDB with this source embedded. All modules that share this symbol file will begin using these updated symbols.

Location constraint: This method can be called from an IDE.

This API was introduced in Visual Studio 16 Update 5 (DkmApiVersion.VS16Update5).

(Inherited from DkmModuleInstance)
Decompile(DkmWorkList, DkmCompletionRoutine<DkmDecompileAsyncResult>)

Decompiles the code for a module into C# and creates a new portable PDB with this source embedded. All modules that share this symbol file will begin using these updated symbols.

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 method can be called from an IDE.

This API was introduced in Visual Studio 16 Update 5 (DkmApiVersion.VS16Update5).

(Inherited from DkmModuleInstance)
FlagAsTransitionModule()

Runtime instances call this method to mark a module as a boundary module. When stepping, runtimes should check if the step has hit a boundary module and start stepping arbitration if they have. Note that some runtimes may not be able to honor this request. The dispatcher will keep a count of the number of times this has been called. Only when a matching number of calls to ClearTransitionModuleFlag have been made will the module no longer be considered a transition module.

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

(Inherited from DkmModuleInstance)
GetBaselineMetaDataBytes()

Obtains the baseline bytes of the CLR metadata from a given module.

This API was introduced in Visual Studio 15 Update 5 (DkmApiVersion.VS15Update5).

GetBaselineMetaDataBytesPtr(UInt32)

Get a pointer to the original raw metadata bytes for the given module.

Location constraint: None.

This API was introduced in Visual Studio 15 Update 5 (DkmApiVersion.VS15Update5).

GetCorObject()

Provides direct access to the ICorDebugModule 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 managed module 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).

GetEncILDelta(Int32)

Responsible for querying the IL delta associated with a CLR module instance. The IL delta are the resulting bytes from a code change, which might affect several methods. This is consumed by VIL when querying information about a modified method within a module.

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

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

GetGPUDisassembly(UInt64, UInt32, Boolean, Boolean)

Obtain the disassembly of the address range in the debuggee module instance.

(Inherited from DkmModuleInstance)
GetGPUDisassemblySize()

Returns the disassembly size in the debuggee module instance.

(Inherited from DkmModuleInstance)
GetLocalSignatureToken(Int32)

Gets the signature token for a local variable signature given a method token.

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

GetMetaDataBytes()

Obtains the bytes of the CLR metadata from a given module. These bytes can then be passed to IMetaDataDispenser::OpenScope to decode the metadata.

GetMetaDataBytesPtr(UInt32)

Get a pointer to the raw metadata bytes for the given module.

NOTE: This pointer value will become invalid if/when the module is a) unloaded or b) modified. To detect these scenarios: a) Add a data item to the module instance or AppDomain. The pointer will be invalid after the OnClose method is called (when the module instance or AppDomain is unloaded). b) Implement IDkmClrModuleModifiedNotification.

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

GetMetaDataFileInfo(Boolean, UInt32, UInt32)

Gets the information needed to read the metadata directly from a file on disk.

This API was introduced in Visual Studio 16 Update 2 (DkmApiVersion.VS16Update2).

GetMetaDataImport()

Obtains the CLR metadata from a given module. See IMetaDataImport documentation in MSDN for more information on metadata.

NOTE: Callers must take great care when consuming this API from managed code. The IMetaDataImport implementation may hold a file handle to a debuggee file, and the file handle will only be closed when the COM reference count hits zero. So it must be manually released (Marshal.IsComObject + Marshal.ReleaseComObject) rather than waiting for the GC to detect that the object can be released. When testing, be sure that the debuggee file has at least 64KB of metadata, as the metadata reader will not keep the file locked for reading when dealing with small files.

GetMetadataStatus()

Get metadata status.

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

GetMethodTokens(DkmWorkList, String, String, DkmCompletionRoutine<DkmGetMethodTokensAsyncResult>)

Provides a mechanism for obtaining metadata tokens for a method given a class. Equivalent to IMetaDataImport::EnumMethodsWithName.

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 API was introduced in Visual Studio 14 RTM (DkmApiVersion.VS14RTM).

GetMethodTokens(String, String, Int32[])

Provides a mechanism for obtaining metadata tokens for a method given a class. Equivalent to IMetaDataImport::EnumMethodsWithName.

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

GetNextGPUInstructionAddress(UInt64)

Returns the address of the next instruction relative to a starting address.

(Inherited from DkmModuleInstance)
GetSymbolLoadInformation()

Returns a string describing the various locations in which symbols were searched for, and the result of checking that location. This information is used to populate the 'Symbol Load Information' in the modules window.

Location constraint: API must be called from an IDE component (component level > 100,000).

(Inherited from DkmModuleInstance)
GetSymbolStatusMessage(Boolean)

Obtain a localized a string description of the current symbol status.

Location constraint: API must be called from an IDE component (component level > 100,000).

(Inherited from DkmModuleInstance)
GetSymbolStatusMessage(DkmWorkList, Boolean, DkmCompletionRoutine<DkmGetSymbolStatusMessageAsyncResult>) (Inherited from DkmModuleInstance)
GetSymUnmanagedReader()

This API provides a partial ISymUnmanagedReader2 implementation for a CLR module.

Location constraint: Provides a partial implementation of ISymUnmanagedReader2 to both sides of the remote connection.

This API was introduced in Visual Studio 15 RTM (DkmApiVersion.VS15RTM).

InterpretManagedMethod(DkmClrMethodId, ReadOnlyCollection<DkmClrType>, ReadOnlyCollection<DkmClrType>, DkmILInterpreterValue, ReadOnlyCollection<DkmILInterpreterValue>, Int32, DkmILInterpreterOptions, String)

Simulates the execution of a method on an object by interpreting the method's MSIL code. The result of the method will be returned back to the caller. However, unlike a function evaluation, in which the method is actually running in the target, interpreting a method does not actually execute the method, but instead, merely simulates the behavior of the method. Because the method never actually executes, any side effects resulting from the method's execution are discarded after the interpretation of the method is complete, leaving the target process in an identical state to that from before the call.

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

IsSuppressed()

This method allows a component to determine if module load event for a module was suppressed.

This API was introduced in Visual Studio 12 Update 3 (DkmApiVersion.VS12Update3).

(Inherited from DkmModuleInstance)
IsTransitionModule()

Returns true if any runtime instance has flagged this module as a transition module.

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

(Inherited from DkmModuleInstance)
IsUserCode()

Determines if a module is considered user code.

Location constraint: This method can be called from an IDE component. Starting in Visual Studio 2013 Update 2, it is also possible to call this from a monitor component for managed code. From Visual Studio 2017 Update 8, the CallDirection of the API was made 'Bidirectional' from 'Normal' and can now be called from any component, AsyncCaller was set to 'true' and the CallerLocationConstraint was set to 'None' from 'NoMarshalling'.

This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).

(Inherited from DkmModuleInstance)
IsUserCode(DkmWorkList, DkmCompletionRoutine<DkmModuleInstanceIsUserCodeAsyncResult>)

Determines if a module is considered user code.

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 method can be called from an IDE component. Starting in Visual Studio 2013 Update 2, it is also possible to call this from a monitor component for managed code. From Visual Studio 2017 Update 8, the CallDirection of the API was made 'Bidirectional' from 'Normal' and can now be called from any component, AsyncCaller was set to 'true' and the CallerLocationConstraint was set to 'None' from 'NoMarshalling'.

This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).

(Inherited from DkmModuleInstance)
OnBinaryLoaded(String)

Raise a BinaryLoaded event. Components which implement the event sink interface will receive the event notification. Control will return once all components have been notified.

This API was introduced in Visual Studio 12 RTM (DkmApiVersion.VS12RTM).

(Inherited from DkmModuleInstance)
OnBinaryReloadOpportunity()

Raise a BinaryReloadOpportunity event. Components which implement the event sink interface will receive the event notification. Control will return once all components have been notified.

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

This API was introduced in Visual Studio 12 Update 2 (DkmApiVersion.VS12Update2).

(Inherited from DkmModuleInstance)
OnModuleModified()

This method is called when a module changes due to EnC or dynamically emitted code.

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

(Inherited from DkmModuleInstance)
OnSymbolsLoaded(DkmModule, Boolean)

This method is invoked by base debug monitors in response to a call to IDkmModuleSymbolsLoaded.RaiseSymbolsLoadedEvent. This method must be invoked from the event thread, or from the request thread as part of a reload. Base debug monitors should synchronously switch to the event thread, pause the target process, and invoke OnSymbolsLoaded.

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

(Inherited from DkmModuleInstance)
OnSymbolsUpdated(DkmModule)

Raise a ModuleSymbolsUpdated event. Components which implement the event sink interface will receive the event notification. Control will return once all components have been notified.

(Inherited from DkmModuleInstance)
ReadSymbols()

This method is invoked by symbol handlers to read symbols for DkmModuleInstances whose symbols reside in debuggee's memory.

(Inherited from DkmModuleInstance)
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)
ResolveTypeName(String, ReadOnlyCollection<DkmClrType>)

Resolves a type name into a type. If the type is generic, the generic parameters will not be instantiated.

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

SetDataItem<T>(DkmDataCreationDisposition, T)

Place a new item in the data container.

(Inherited from DkmDataContainer)
SetDisabled(Boolean)

Updates the disabled status on a module. This method may only be called from a ModuleInstanceLoad event. When disabling a module, it is common to also suppress the module load event.

(Inherited from DkmModuleInstance)
SetModule(DkmModule, Boolean)

This method is invoked by a symbol provider to associate a DkmModule with a DkmModuleInstance and to trigger a ModuleSymbolsLoaded event. It may be called only once for a DkmModuleInstance object. Calling this API will both establish the DkmModule<->DkmModuleInstance association, as well as cause a ModuleSymbolsLoaded event to be raised.

(Inherited from DkmModuleInstance)
TryLoadBinary()

Attempt to load a binary that previously failed to load using updated symbol paths.

Location constraint: API must be called from an IDE component (component level > 100,000).

(Inherited from DkmModuleInstance)
TryLoadBinary(DkmWorkList, DkmCompletionRoutine<DkmTryLoadBinaryAsyncResult>)

Attempt to load a binary that previously failed to load using updated symbol paths.

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 DkmModuleInstance)
TryLoadSymbols()

Called to initiate loading of symbols for DkmModuleInstances whose symbols were not found when the module loaded.

Location constraint: API must be called from an IDE component (component level > 100,000).

(Inherited from DkmModuleInstance)
TryLoadSymbols(DkmWorkList, DkmCompletionRoutine<DkmTryLoadSymbolsAsyncResult>)

Called to initiate loading of symbols for DkmModuleInstances whose symbols were not found when the module loaded.

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 DkmModuleInstance)
TryLoadSymbolsCallback() (Inherited from DkmModuleInstance)
TryLoadSymbolsCallback(DkmWorkList, DkmCompletionRoutine<DkmTryLoadSymbolsCallbackAsyncResult>) (Inherited from DkmModuleInstance)
Unload()

Mark the Unload object as unloaded and notify components which implement the event sink interface. Control will return once all components have been notified.

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

(Inherited from DkmModuleInstance)

Applies to