DkmModule Class

Definition

Namespace:

Microsoft.VisualStudio.Debugger.Symbols

Assembly:

Microsoft.VisualStudio.Debugger.Engine.dll

The DkmModule class represents a code bundle (ex: dll or exe) which is or once was loaded into one or more processes. The DkmModule class is the central object to the symbol APIs, and is 1:1 with the symbol handler's notation of what is loaded. If a code bundle loads into three different processes (or the same process but with three different base addresses or three different app domains) but the symbol handler thinks of all of these as being identical, there will be only one module object.

public ref class DkmModule : Microsoft::VisualStudio::Debugger::DkmDataContainer

[System.Runtime.InteropServices.Guid("9fdf7d9f-e5ab-b363-6282-1da170173343")]
public class DkmModule : Microsoft.VisualStudio.Debugger.DkmDataContainer

[<System.Runtime.InteropServices.Guid("9fdf7d9f-e5ab-b363-6282-1da170173343")>]
type DkmModule = class
    inherit DkmDataContainer

Public Class DkmModule
Inherits DkmDataContainer

Inheritance

MarshalByRefObject

DkmDataContainer

DkmModule

Attributes

GuidAttribute

Properties

CompilerId	LanguageId/VendorId for the compiler which produced all of the code in this module. This is Guid.Empty/Guid.Empty if the module may contain a mixture of languages. This will almost always be Guid.Empty/Guid.Empty for PDB-based modules. It generally used by dynamic languages to avoid network round trips to discover the language of each symbol.
Connection	[Optional] For modules where symbols are loaded remotely, the connection property is used to determine where the Connection originated from. Otherwise this will be NULL.
FilePath	[Optional] If specified, this contains the full path to the symbol file which backs the DkmModule (ex: c:\myproj\bin\Debug\myproj.pdb). This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTMPreview).
Flags
Id	Guid pair used to uniquely identify a particular DkmModule instance.
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)
Name	Name of the module.
SymbolsConnection	[Optional] If non-null, this specifies a connection to a worker process where symbols for this DkmModule are processed. This will be null if symbols are loaded in the IDE process, or if they are loaded in the remote debugger (DkmModule.Connection is non-null). This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTMPreview).

Methods

Create(DkmModuleId, String, DkmCompilerId, DkmTransportConnection, DkmDataItem)	Creates a new DkmModule object, which represents the symbols for one or more loaded modules (module instances). These objects are created by symbol providers. After the DkmModule object is created, symbol providers should call DkmModuleInstance.SetModule to associate the DkmModuleInstance and DkmModule together. This method will send a ModuleCreate event.
Create(DkmModuleId, String, DkmCompilerId, DkmTransportConnection, DkmWorkerProcessConnection, String, DkmDataItem)	Creates a new DkmModule object, which represents the symbols for one or more loaded modules (module instances). These objects are created by symbol providers. After the DkmModule object is created, symbol providers should call DkmModuleInstance.SetModule to associate the DkmModuleInstance and DkmModule together. This method will send a ModuleCreate event. This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTMPreview).
Create(DkmModuleId, String, DkmCompilerId, DkmTransportConnection, DkmWorkerProcessConnection, String, DkmModuleSymbolFlags, DkmDataItem)
EnumSymbolsDocuments()	Enumerates the symbol documents of the symbols file associated with the module. 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).
EnumSymbolsDocuments(DkmWorkList, DkmCompletionRoutine<DkmEnumSymbolsDocumentsAsyncResult>)
FindDocuments(DkmSourceFileId)	Returns document objects from search parameters contained in the document query. If the symbol file does not contain a reference to this document the returned document object will be NULL (S_FALSE return code in native). The returned document objects must be explicitly closed by the caller when the caller is done with the document. Location constraint: API must be called from an IDE component (component level > 100,000).
FindDocuments(DkmWorkList, DkmSourceFileId, DkmCompletionRoutine<DkmFindDocumentsAsyncResult>)	Returns document objects from search parameters contained in the document query. If the symbol file does not contain a reference to this document the returned document object will be NULL (S_FALSE return code in native). The returned document objects must be explicitly closed by the caller when the caller is done with the document. 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).
FindModule(DkmModuleId)	Find a DkmModule object. If no object with the given input key is present, FindModule will fail.
GetAcceleratorTagTableSize(UInt32)	Gets a C++ AMP address for a register. Location constraint: API must be called from an IDE component (component level > 100,000).
GetCompilerOptions()	This method returns compiler flags of the given GPU module.
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)
GetEntryPointSymbols()	GetEntryPointSymbols is used by the breakpoint manager to find the entry point symbol(s) in the launching executable. For managed code, this symbol is defined using ISymUnmanagedWriter::SetUserEntryPoint. For native code, this symbol is found by looking for the various 'main' function (main, WinMain, etc). A third can override the entry point either by implementing their own symbol provider or by implementing IDkmEntryPointQuery. Location constraint: API must be called from a Monitor component (component level < 100,000).
GetFirstMethodInFirstDocument()	Returns the first method in the first document.
GetFunctionInfo(DkmWorkList, String, DkmCompletionRoutine<DkmGetFunctionInfoAsyncResult>)	Search a module's symbols for a function with the specified name. Returns the RVA and size if it is found. 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).
GetFunctionInfo(String)	Search a module's symbols for a function with the specified name. Returns the RVA and size if it is found. Location constraint: API must be called from a Monitor component (component level < 100,000).
GetFunctionLabels(UInt64)	Gets the symbol name for the RVA. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 Update 3 (DkmApiVersion.VS16Update3).
GetFunctionRva(UInt64)	Gets the RVA of the function containing the specified RVA. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 Update 3 (DkmApiVersion.VS16Update3).
GetInstructionOffsetForRva(UInt32)	GetInstructionOffsetForRva is used by components to query symbol provider to perform instruction offset and RVA translation for DPC++. Location constraint: API must be called from an IDE component (component level > 100,000).
GetLinkerFixupRecords()	Fetches the linker fixup records for the module. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM).
GetMethodSymbolStoreData(DkmClrMethodId)	Returns the scopes within a method. There will always be at least one scope.
GetMethodSymbolStoreData(DkmWorkList, DkmClrMethodId, DkmCompletionRoutine<DkmGetMethodSymbolStoreDataAsyncResult>)	Returns the scopes within a method. There will always be at least one scope. 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.
GetMethodSymbolStoreDataPreRemap(DkmClrMethodId, Int32)	Returns the scopes within a method. There will always be at least one scope.
GetMethodSymbolStoreDataPreRemap(DkmWorkList, DkmClrMethodId, DkmCompletionRoutine<DkmGetMethodSymbolStoreDataPreRemapAsyncResult>)	Returns the scopes within a method. There will always be at least one scope. 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.
GetModuleInstances()	A DkmModule is the symbol handler's representation of a module, and is not bound to any process, connection or runtime instance. This method returns all the DkmModuleInstances which map to this DkmModule. A DkmModule can be bound to zero instances in the case that all of the modules are now unloaded. In this case, GetModuleInstances will return an empty array (S_FALSE return code in native).
GetModules()	GetModules enumerates all the created DkmModule objects.
GetPointerToHLSLRegister(Int32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, Boolean)	Gets a C++ AMP address for a register. Location constraint: API must be called from an IDE component (component level > 100,000).
GetPublicSymbolByNameCallback(DkmWorkList, String, DkmCompletionRoutine<DkmGetPublicSymbolByNameCallbackAsyncResult>)	Return the RVA for an S_PUBLIC32 for a particular name by string. 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.
GetPublicSymbolByNameCallback(String)	Return the RVA for an S_PUBLIC32 for a particular name by string.
GetRegisterRelativeSymbolName(DkmWorkList, UInt32, Int32, UInt32, DkmProcessorArchitecture, DkmCompletionRoutine<DkmGetRegisterRelativeSymbolNameAsyncResult>)	Gets the symbol name for a register relative value. 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 RTM (DkmApiVersion.VS16RTM).
GetRegisterRelativeSymbolName(UInt32, Int32, UInt32, DkmProcessorArchitecture)	Gets the symbol name for a register relative value. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM).
GetScriptDocuments()	GetScriptDocuments enumerates the DkmScriptDocument elements of this DkmModule object.
GetSourceLinkData(DkmModuleInstance)
GetSourceLinkData(DkmWorkList, DkmModuleInstance, DkmCompletionRoutine<DkmGetSourceLinkDataAsyncResult>)
GetSourceLinkInfo(String)	Returns SourceLink information from the symbol file for the requested file path. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 15 RTM (DkmApiVersion.VS15RTM).
GetSourceServerData(DkmModuleInstance)	Returns the contents of the source server stream data for a module if the stream exists. Location constraint: API must be called from an IDE component (component level > 100,000).
GetSourceServerData(DkmWorkList, DkmModuleInstance, DkmCompletionRoutine<DkmGetSourceServerDataAsyncResult>)
GetSymbolFilePath()	Returns the path to the symbol file which backs a DkmModule object. Location constraint: API must be called from an IDE component (component level > 100,000).
GetSymbolFilePath(DkmWorkList, DkmCompletionRoutine<DkmGetSymbolFilePathAsyncResult>)
GetSymbolFileRawBytes()	GetSymbolFileRawBytes is used to retrieve the raw bytes of a symbol file from the remote side. This is currently only supported for dynamic portable PDBs. This will return at most 10 MB. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 14 Update 3 Micro Update (DkmApiVersion.VS14Update3MicroUpdate).
GetSymbolInterface(Guid)	GetSymbolInterface is used to obtain a raw COM interface to a symbol store. This is useful to either callers that find the symbol abstraction presented by the debugger to be either too restrictive for their needs, or simply undesirable due to how their component is implemented. Location constraint: With the exception of managed symbols, this method must be called from the same process where the symbol provider has opened the symbol file. For Native PDB files, this means that the API must be called from the IDE process. For Managed symbols, a subset of the symbol provider API is provided on both sides of the remote connection.
GetSymbolNameForRVA(DkmWorkList, UInt32, DkmCompletionRoutine<DkmGetSymbolNameForRVAAsyncResult>)	Gets the symbol name for the RVA. 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 RTM (DkmApiVersion.VS16RTM).
GetSymbolNameForRVA(UInt32, UInt64)	Gets the symbol name for the RVA. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTM).
GetTokenSymbolStoreAttribute(DkmWorkList, Int32, Boolean, String, DkmCompletionRoutine<DkmGetTokenSymbolStoreAttributeAsyncResult>)	Gets a custom attribute based upon its name. Not to be confused with Metadata custom attributes, these attributes are held in the symbol store. 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.
GetTokenSymbolStoreAttribute(Int32, Boolean, String)	Gets a custom attribute based upon its name. Not to be confused with Metadata custom attributes, these attributes are held in the symbol store.
IsValidAcceleratorTag(UInt32, UInt32)	Verify if the accelerator pointer tag is valid. Location constraint: API must be called from an IDE 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)
SetDataItem<T>(DkmDataCreationDisposition, T)	Place a new item in the data container. (Inherited from DkmDataContainer)
SetPointerToHLSLRegister(UInt64, Int32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32)	Sets a C++ AMP address for a register. Location constraint: API must be called from an IDE component (component level > 100,000).
SymbolsHaveEmbeddedDocuments()	Checks if the symbols associated with the module have embedded documents. 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).
TranslateAcceleratorTagByIP(UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32)	Translate accelerator pointer tag into HLSL register attributes.
TranslateAcceleratorTagByRva(UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32, UInt32)	Translate accelerator pointer tag into HLSL register attributes using relative virtual address. Location constraint: API must be called from an IDE component (component level > 100,000).
UndecorateName(String, UInt32)	Undecorates a symbol name. Location constraint: API must be called from an IDE component (component level > 100,000).