DkmCustomInstructionSymbol Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
DkmCustomInstructionSymbol is used to represent an executable statement in any type of custom runtime environment.
public ref class DkmCustomInstructionSymbol : Microsoft::VisualStudio::Debugger::Symbols::DkmInstructionSymbol[Windows::Foundation::Metadata::WebHostHidden]
public ref class DkmCustomInstructionSymbol : Microsoft::VisualStudio::Debugger::Symbols::DkmInstructionSymbol[Windows::Foundation::Metadata::WebHostHidden]
class DkmCustomInstructionSymbol : Microsoft::VisualStudio::Debugger::Symbols::DkmInstructionSymbol[System.Runtime.InteropServices.Guid("c154cde9-82a7-6e6f-f4f4-8dbb776da068")]
public class DkmCustomInstructionSymbol : Microsoft.VisualStudio.Debugger.Symbols.DkmInstructionSymbol[<System.Runtime.InteropServices.Guid("c154cde9-82a7-6e6f-f4f4-8dbb776da068")>]
type DkmCustomInstructionSymbol = class
inherit DkmInstructionSymbolPublic Class DkmCustomInstructionSymbol
Inherits DkmInstructionSymbol- Inheritance
- Attributes
Properties
| AdditionalData |
[Optional] Additional runtime-specific data associated with an address. This data will not be used when comparing addresses. |
| EntityId |
[Optional] This is a runtime-specific data structure which custom runtimes may use to store the location of this instruction. Along with 'offset', this field will used to compare two instructions from the same module. |
| Module |
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. (Inherited from DkmInstructionSymbol) |
| Offset |
Along with 'EntityId' the 'Offset' field is used to uniquely identity an instruction. This could hold a pointer value (such as a pointer to the instruction) or an offset from the start of the function/module. |
| RuntimeType |
The Runtime Id identifies the execution environment for a particular piece of code. Runtime Ids are used by the dispatcher to decide which monitor to dispatch to. Note that the ordering of the runtime ID Guids is somewhat significant as this dictates which runtime gets the first shot during arbitration. Thus, if one wants to declare a new runtime instance which is built on the CLR, the runtime id should be less than DkmRuntimeId.Clr. (Inherited from DkmInstructionSymbol) |
| TagValue |
DkmInstructionSymbol is an abstract base class. This enum indicates which derived class this object is an instance of. (Inherited from DkmInstructionSymbol) |
Methods
| Bind(DkmModuleInstance) |
Binds an instruction symbol to a particular module instance. An instruction symbol is connected to a DkmModule rather than a DkmModuleInstance, so it is not bound to a particular process, app domain, or module base address. (Inherited from DkmInstructionSymbol) |
| Create(DkmModule, Guid, ReadOnlyCollection<Byte>, UInt64, ReadOnlyCollection<Byte>) |
Create a new DkmCustomInstructionSymbol object instance. |
| GetAlternateSourcePosition(DkmSourcePositionFlags) |
Returns an alternate source file position (ex: example.cs, line 12) for this instruction symbol. This is currently used in source map scenarios to return the original (unmapped) source location. This API will be called by the debugger UI in cases where the primary source location cannot be found. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 12 Update 3 (DkmApiVersion.VS12Update3). (Inherited from DkmInstructionSymbol) |
| GetBasicInfo(DkmWorkList, DkmModuleInstance, DkmBasicSymbolInfoRequestFlags, DkmCompletionRoutine<DkmGetBasicSymbolInfoAsyncResult>) |
Asynchronously computes basic symbol information for a given DkmInstructionSymbol. 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.VS16RTMPreview). (Inherited from DkmInstructionSymbol) |
| GetCompilerId(DkmInspectionSession) |
Returns the compiler id (LanguageId/VendorId) of a given symbol. For the Microsoft PDB reader, if the PDB was created by a compiler which used ISymUnmanagedWriter, then the PDB reader will be able to determine the correct DkmCompilerId from the LanguageId/VendorId pair passed from ISymUnmanagedWriter.DefineDocument. If the PDB was created by a compiler which did not use ISymUnmanagedWriter, the PDB reader may be able to obtain the DkmCompilerId from the S_COMPILE* PDB records. For this to work, the compiler must first emit the S_COMPILE* record for each compiland. The compiler needs to be sure to correctly fill out the language enumeration value, and the compiler string. The compiler should ensure that the compiler string is sufficiently specific to use for selecting an expression evaluator; it is recommended to include a company name. After emitting the Enum/Name pair, the setup for the expression evaluator should then register this pair with the debugger. To do so, the expression evaluator should set this registry key: %VSRegistryRoot%\Debugger\CodeView Compilers%CodeViewLanguageCode%:%CompilerName% and define the VendorId/LanguageId. (Inherited from DkmInstructionSymbol) |
| GetCompilerId(DkmWorkList, DkmInspectionSession, DkmCompletionRoutine<DkmGetCompilerIdAsyncResult>) |
Returns the compiler id (LanguageId/VendorId) of a given symbol. For the Microsoft PDB reader, if the PDB was created by a compiler which used ISymUnmanagedWriter, then the PDB reader will be able to determine the correct DkmCompilerId from the LanguageId/VendorId pair passed from ISymUnmanagedWriter.DefineDocument. If the PDB was created by a compiler which did not use ISymUnmanagedWriter, the PDB reader may be able to obtain the DkmCompilerId from the S_COMPILE* PDB records. For this to work, the compiler must first emit the S_COMPILE* record for each compiland. The compiler needs to be sure to correctly fill out the language enumeration value, and the compiler string. The compiler should ensure that the compiler string is sufficiently specific to use for selecting an expression evaluator; it is recommended to include a company name. After emitting the Enum/Name pair, the setup for the expression evaluator should then register this pair with the debugger. To do so, the expression evaluator should set this registry key: %VSRegistryRoot%\Debugger\CodeView Compilers%CodeViewLanguageCode%:%CompilerName% and define the VendorId/LanguageId. 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.VS16RTMPreview). (Inherited from DkmInstructionSymbol) |
| GetCurrentStatementRange() |
This method returns the IL offset range that contains the current IL offset as specified in the instruction address. Location constraint: API must be called from a Monitor component (component level < 100,000). (Inherited from DkmInstructionSymbol) |
| GetDisassemblyLabel(DkmInspectionSession) |
Return the name of the symbol as it should appear in the disassembly window. For Microsoft C++ code, this is based on the public symbol name. Location constraint: API must be called from an IDE component (component level > 100,000). (Inherited from DkmInstructionSymbol) |
| GetEmbeddedDocument() |
Returns the embedded document containing this symbol. Returns S_FALSE if the embedded document does not exist. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 15 Update 5 (DkmApiVersion.VS15Update5). (Inherited from DkmInstructionSymbol) |
| GetGPUInstructionMetadataCallback(DkmInstructionAddress, DkmInstructionSymbol) |
This method returns address information to the GPU debug monitor. (Inherited from DkmInstructionSymbol) |
| GetInlineFramesCount(DkmBasicSymbolInfoRequestFlags) |
Returns the number of inline frames at the given instruction symbol. Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTMPreview). (Inherited from DkmInstructionSymbol) |
| GetInlineFramesCount(DkmWorkList, DkmBasicSymbolInfoRequestFlags, DkmCompletionRoutine<DkmGetInlineFramesCountAsyncResult>) |
Returns the number of inline frames at the given instruction symbol. 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.VS16RTMPreview). (Inherited from DkmInstructionSymbol) |
| GetInlineSourcePosition(DkmStackWalkFrame, Boolean) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol at the specified inline frame number. If this instruction symbol is not associated with a source file then null is returned (S_FALSE return code in native). 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). (Inherited from DkmInstructionSymbol) |
| GetInlineSourcePosition(DkmWorkList, DkmStackWalkFrame, DkmCompletionRoutine<DkmGetInlineSourcePositionAsyncResult>) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol at the specified inline frame number. If this instruction symbol is not associated with a source file then null is returned (S_FALSE return code in native). 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 15 RTM (DkmApiVersion.VS15RTM). (Inherited from DkmInstructionSymbol) |
| GetNoSourceRanges() |
Queries the symbol provider to determine the ranges of instructions which do not correspond to any user source statements and are used by the base debug monitor to always step through during stepping. (Inherited from DkmInstructionSymbol) |
| GetSourcePosition(DkmSourcePositionFlags, DkmInspectionSession, Boolean) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol. If this instruction symbol is not associated with a source file then null is returned (S_FALSE return code in native). Location constraint: API must be called from an IDE component (component level > 100,000). (Inherited from DkmInstructionSymbol) |
| GetSourcePosition(DkmWorkList, DkmSourcePositionFlags, DkmInspectionSession, DkmCompletionRoutine<DkmGetSourcePositionAsyncResult>) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol. If this instruction symbol is not associated with a source file then null is returned (S_FALSE return code in native). 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 DkmInstructionSymbol) |
| GetSourcePositionCallback(DkmSourcePositionFlags, DkmInspectionSession, Boolean) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol. If this instruction symbol is not associated with a source file then null is returned (S_FALSE return code in native). Location constraint: API must be called from a Monitor component (component level < 100,000). (Inherited from DkmInstructionSymbol) |
| GetSourcePositionCallback(DkmWorkList, DkmSourcePositionFlags, DkmInspectionSession, DkmCompletionRoutine<DkmGetSourcePositionCallbackAsyncResult>) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol. If this instruction symbol is not associated with a source file then null is returned (S_FALSE return code in native). 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). (Inherited from DkmInstructionSymbol) |
| GetSteppingRanges(DkmSteppingRangeBoundary, Boolean) |
Queries the symbol provider to determine the ranges of instructions which the base debug monitor should step through to implement a step. Location constraint: API must be called from a Monitor component (component level < 100,000). (Inherited from DkmInstructionSymbol) |
| GetSteppingRanges(DkmWorkList, DkmSteppingRangeBoundary, Boolean, DkmCompletionRoutine<DkmGetSteppingRangesAsyncResult>) | (Inherited from DkmInstructionSymbol) |
| GetUserCodeSourcePositionCallback(DkmInspectionSession) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol. If this instruction symbol is not associated with a source file or not in user code then null is returned (E_INSTRUCTION_NO_SOURCE return code). Location constraint: API must be called from a Monitor component (component level < 100,000). (Inherited from DkmInstructionSymbol) |
| GetUserCodeSourcePositionCallback(DkmWorkList, DkmInspectionSession, DkmCompletionRoutine<DkmGetUserCodeSourcePositionCallbackAsyncResult>) |
Returns the source file position (ex: example.cs, line 12) of this instruction symbol. If this instruction symbol is not associated with a source file or not in user code then null is returned (E_INSTRUCTION_NO_SOURCE return 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: API must be called from a Monitor component (component level < 100,000). (Inherited from DkmInstructionSymbol) |
| HasEmbeddedDocument() |
Tests if the given symbol has an embedded document. Embedded documents are when a source file (ex: main.cs) is embedded inside the symbol file (ex: example.pdb). Location constraint: API must be called from an IDE component (component level > 100,000). This API was introduced in Visual Studio 15 Update 8 (DkmApiVersion.VS15Update8). (Inherited from DkmInstructionSymbol) |
| HasLineInfo() |
Queries the symbol provider to determine if we have line info. Used by debug monitor to decide if location can be considered user code. Location constraint: For ordinary symbols, can be called from any component. For dynamic symbols, can only be called on the server side. (Inherited from DkmInstructionSymbol) |
| HasLineInfo(DkmWorkList, DkmCompletionRoutine<DkmHasLineInfoAsyncResult>) |
Queries the symbol provider to determine if we have line info. Used by debug monitor to decide if location can be 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: For ordinary symbols, can be called from any component. For dynamic symbols, can only be called on the server side. (Inherited from DkmInstructionSymbol) |
| IsHiddenCode(DkmWorkList, DkmInspectionSession, DkmInstructionAddress, DkmCompletionRoutine<DkmIsHiddenCodeAsyncResult>) |
Returns if this instruction symbol is in hidden code. For instance, in managed code, the line number 0xfeefee marks a source line as hidden. 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 DkmInstructionSymbol) |