Share via


DkmCustomModuleInstance Class

Definition

'DkmCustomModuleInstance' is used for modules from a custom runtime environment (not native or CLR-based). For example, this could be used in a custom interpreter or Just-In-Time compiler.

public ref class DkmCustomModuleInstance : Microsoft::VisualStudio::Debugger::DkmModuleInstance
[System.Runtime.InteropServices.Guid("28a2ee07-bdcf-31f8-66e9-09b958e66fe8")]
public class DkmCustomModuleInstance : Microsoft.VisualStudio.Debugger.DkmModuleInstance
[<System.Runtime.InteropServices.Guid("28a2ee07-bdcf-31f8-66e9-09b958e66fe8")>]
type DkmCustomModuleInstance = class
    inherit DkmModuleInstance
Public Class DkmCustomModuleInstance
Inherits DkmModuleInstance
Inheritance
Inheritance
DkmCustomModuleInstance
Attributes

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.

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

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

(Inherited from DkmModuleInstance)
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, DkmRuntimeInstance, DkmModuleVersion, DkmSymbolFileId, DkmModuleFlags, DkmModuleMemoryLayout, UInt64, UInt32, UInt32, String, Boolean, DkmModule, DkmModuleInstance+MinidumpInfo, DkmDataItem)

Create a new DkmCustomModuleInstance object instance.

This method will send a ModuleInstanceLoad event.

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: API must be called from an IDE component (component level > 100,000).

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: API must be called from an IDE component (component level > 100,000).

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

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

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. Implementations should return S_OK on failure and return the actual HRESULT and any additional error information via the 'HR' and 'ErrorMessage' parameters.

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 17 Update 3 (DkmApiVersion.VS17Update3).

(Inherited from DkmModuleInstance)
Decompile(String, Int32)

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. Implementations should return S_OK on failure and return the actual HRESULT and any additional error information via the 'HR' and 'ErrorMessage' parameters.

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

This API was introduced in Visual Studio 17 Update 3 (DkmApiVersion.VS17Update3).

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

(Inherited from DkmModuleInstance)
GetGPUDisassemblySize()

Returns the disassembly size in the debuggee module instance.

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

Retrieves any symbol search results associated with this module instance.

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

This API was introduced in Visual Studio 17 Update 3 (DkmApiVersion.VS17Update3).

(Inherited from DkmModuleInstance)
GetSymbolSearchResult(DkmWorkList, DkmCompletionRoutine<DkmGetSymbolSearchResultAsyncResult>)

Retrieves any symbol search results associated with this module 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 17 Update 3 (DkmApiVersion.VS17Update3).

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

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

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

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

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

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

This API was introduced in Visual Studio 17 Update 4 (DkmApiVersion.VS17Update4).

(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)
TryLoadSymbols(DkmWorkList, DkmSymbolLoadFlags, 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).

This API was introduced in Visual Studio 17 Update 4 (DkmApiVersion.VS17Update4).

(Inherited from DkmModuleInstance)
TryLoadSymbolsCallback()

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

Location constraint: This can be called from the client or the server. The server implementation of this is a cache to prevent unnecessary network calls. The client goes directly to the 'real' implementation which also ensures that reattempts return early.

This API was introduced in Visual Studio 17 RTM (DkmApiVersion.VS17RTM).

(Inherited from DkmModuleInstance)
TryLoadSymbolsCallback(DkmWorkList, DkmCompletionRoutine<DkmTryLoadSymbolsCallbackAsyncResult>)

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: This can be called from the client or the server. The server implementation of this is a cache to prevent unnecessary network calls. The client goes directly to the 'real' implementation which also ensures that reattempts return early.

This API was introduced in Visual Studio 17 RTM (DkmApiVersion.VS17RTM).

(Inherited from DkmModuleInstance)
TryLoadSymbolsCallback177(DkmSymbolLoadFlags)

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

Location constraint: This can be called from the client or the server. The server implementation of this is a cache to prevent unnecessary network calls. The client goes directly to the 'real' implementation which also ensures that reattempts return early.

This API was introduced in Visual Studio 17 Update 7 (DkmApiVersion.VS17Update7).

(Inherited from DkmModuleInstance)
TryLoadSymbolsCallback177(DkmWorkList, DkmSymbolLoadFlags, DkmCompletionRoutine<DkmTryLoadSymbolsCallback177AsyncResult>)

Called to initiate loading of locally present 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: This can be called from the client or the server. The server implementation of this is a cache to prevent unnecessary network calls. The client goes directly to the 'real' implementation which also ensures that reattempts return early.

This API was introduced in Visual Studio 17 Update 7 (DkmApiVersion.VS17Update7).

(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