DkmModuleInstance Class

Definition

Namespace:

Microsoft.VisualStudio.Debugger

Assembly:

Microsoft.VisualStudio.Debugger.Engine.dll

The Module Instance class represent a code bundle (ex: dll or exe) which is loaded into a particular process at a particular location. Module Instance objects are 1:1 with the execution environment's notion of a code bundle. For example, in native code, Module Instance objects are 1:1 with base address.

Derived classes: DkmClrModuleInstance, DkmClrNcModuleInstance, DkmCustomModuleInstance, DkmNativeModuleInstance, DkmClrNcContainerModuleInstance

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

[System.Runtime.InteropServices.Guid("74857b6f-618d-66e3-149e-6cebf4c4123e")]
public abstract class DkmModuleInstance : Microsoft.VisualStudio.Debugger.DkmDataContainer

[<System.Runtime.InteropServices.Guid("74857b6f-618d-66e3-149e-6cebf4c4123e")>]
type DkmModuleInstance = class
    inherit DkmDataContainer

Public MustInherit Class DkmModuleInstance
Inherits DkmDataContainer

Inheritance

MarshalByRefObject

DkmDataContainer

DkmModuleInstance

Derived

Microsoft.VisualStudio.Debugger.Clr.DkmClrModuleInstance

Microsoft.VisualStudio.Debugger.Clr.NativeCompilation.DkmClrNcContainerModuleInstance

Microsoft.VisualStudio.Debugger.CustomRuntimes.DkmCustomModuleInstance

Microsoft.VisualStudio.Debugger.Native.DkmNativeModuleInstance

Attributes

GuidAttribute

Properties

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.
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.
Flags	Flags which indicate traits of a DkmModuleInstance.
FullName	Fully qualified module name. For file-based modules, this is the full path to the module (ex: c:\windows\system32\kernel32.dll.
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.
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'.
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.
MemoryLayout	Enumeration that indicates how a module is laid out in memory.
MinidumpInfoPart	[Optional] 'MinidumpInfoPart' is used to convey additional information about modules in a DkmProcess for a minidump.
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.
Name	Short representation of the module name. For file-based modules, this is the file name and extension (ex: kernel32.dll).
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.
RuntimeInstance	The DkmRuntimeInstance class represents an execution environment which is loaded into a DkmProcess and which contains code to be debugged.
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.
SymbolFileId	[Optional] Contains information needed to locate symbols for this module. On Win32, this information is contained within the IMAGE_DEBUG_DIRECTORY.
TagValue	DkmModuleInstance is an abstract base class. This enum indicates which derived class this object is an instance of.
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).
UniqueId	Uniquely identifies the DkmModuleInstance object.
Version	[Optional] File version information.

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).
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).
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).
Decompile(DkmWorkList, DkmCompletionRoutine<DkmDecompileAsyncResult173>)
Decompile(String, Int32)
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).
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)
GetGPUDisassembly(UInt64, UInt32, Boolean, Boolean)	Obtain the disassembly of the address range in the debuggee module instance.
GetGPUDisassemblySize()	Returns the disassembly size in the debuggee module instance.
GetNextGPUInstructionAddress(UInt64)	Returns the address of the next instruction relative to a starting address.
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).
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).
GetSymbolStatusMessage(DkmWorkList, Boolean, DkmCompletionRoutine<DkmGetSymbolStatusMessageAsyncResult>)
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).
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).
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).
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).
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).
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).
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).
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).
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.
ReadSymbols()	This method is invoked by symbol handlers to read symbols for DkmModuleInstances whose symbols reside in debuggee's memory.
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)
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.
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.
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).
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).
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).
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).
TryLoadSymbolsCallback()
TryLoadSymbolsCallback(DkmWorkList, DkmCompletionRoutine<DkmTryLoadSymbolsCallbackAsyncResult>)
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.