DkmClrInstructionSymbol Class

Definition

DkmClrInstructionSymbol represents an IL instruction that runs under the Common Language Runtime (CLR) in the target process. This object contains the method version number. So in Edit-and-Continue scenarios, the instruction symbol would be different for different versions of the method. This object does not contain information about generic binding parameters. So different generic instantiations of a method (ex: MyMethod<string> and MyMethod<int>) are represented by the same instruction symbol since the CLR represents them with a single method token.

Derived classes: DkmClrNcInstructionSymbol

public ref class DkmClrInstructionSymbol : Microsoft::VisualStudio::Debugger::Symbols::DkmInstructionSymbol
[Windows::Foundation::Metadata::WebHostHidden]
public ref class DkmClrInstructionSymbol : Microsoft::VisualStudio::Debugger::Symbols::DkmInstructionSymbol
[Windows::Foundation::Metadata::WebHostHidden]
class DkmClrInstructionSymbol : Microsoft::VisualStudio::Debugger::Symbols::DkmInstructionSymbol
[System.Runtime.InteropServices.Guid("8e7388ae-e3e2-122c-5560-09f77dfaed9d")]
public class DkmClrInstructionSymbol : Microsoft.VisualStudio.Debugger.Symbols.DkmInstructionSymbol
[<System.Runtime.InteropServices.Guid("8e7388ae-e3e2-122c-5560-09f77dfaed9d")>]
type DkmClrInstructionSymbol = class
    inherit DkmInstructionSymbol
Public Class DkmClrInstructionSymbol
Inherits DkmInstructionSymbol
Inheritance
DkmClrInstructionSymbol
Derived
Attributes

Properties

ILOffset

ILOffset is the index of the IL instruction that this symbol represents. This value may be set to UInt32.MaxValue for an instruction that is within the given method, but not tied to a particular instruction. This is used for CLR native instructions that don't map to an IL instruction.

MethodId

The version/token pair for this method.

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)
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, DkmClrMethodId, UInt32)

Create a new DkmClrInstructionSymbol object instance.

GetAllAwaitExpressionInfoForStatement()

Gets the yield and resume points contained within the statement surrounding the given instruction symbol.

GetAllAwaitExpressionInfoForStatement(DkmWorkList, DkmCompletionRoutine<DkmGetAllAwaitExpressionInfoForStatementAsyncResult>)

Gets the yield and resume points contained within the statement surrounding 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.

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

If the current method is an async method then return the kickoff method for this async method.

GetAsyncKickoffMethod(DkmWorkList, DkmCompletionRoutine<DkmGetAsyncKickoffMethodAsyncResult>)

If the current method is an async method then return the kickoff method for this async method.

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.

GetAsyncMethodCatchHandlerILOffset(UInt32)

Gets the optional starting IL offset of an async method's generated catch handler.

GetAsyncMethodLocation()

Gets the location of the instruction symbol in it's method.

GetAsyncMethodLocation(DkmWorkList, DkmCompletionRoutine<DkmGetAsyncMethodLocationAsyncResult>)

Gets the location of the instruction symbol in it's method.

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.

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

Obtains the parameters to the managed C++ function represented by the given function symbol.

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

This API was introduced in Visual Studio 14 Update 1 (DkmApiVersion.VS14Update1).

GetManagedCppMethodScope(DkmNativeCppInspectionSession)

Returns symbol information concerning the innermost active scope of the location indicated by the given instruction symbol, which is assumed to have been compiled with managed C++.

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

This API was introduced in Visual Studio 14 Update 1 (DkmApiVersion.VS14Update1).

GetMethodLocalSymbols()

Returns the scopes within a method. There will always be at least one scope.

Location constraint: This API will fail when called from an IDE component to query information for server-side compiled ASP.NET code, or dynamically compiled code.

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

GetMethodLocalSymbols(DkmWorkList, DkmCompletionRoutine<DkmGetMethodLocalSymbolsAsyncResult>)

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.

Location constraint: This API will fail when called from an IDE component to query information for server-side compiled ASP.NET code, or dynamically compiled code.

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

GetMethodSymbolStoreAttribute(DkmWorkList, String, DkmCompletionRoutine<DkmGetMethodSymbolStoreAttributeAsyncResult>)

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.

Location constraint: This API will fail when called from an IDE component to query information for server-side compiled ASP.NET code, or dynamically compiled code.

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

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

Location constraint: This API will fail when called from an IDE component to query information for server-side compiled ASP.NET code, or dynamically compiled code.

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

GetNextAwaitExpressionInfo()

Get the yield and resume information of the next await expression.

GetNextAwaitExpressionInfo(DkmWorkList, DkmCompletionRoutine<DkmGetNextAwaitExpressionInfoAsyncResult>)

Get the yield and resume information of the next await expression.

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.

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

Gets the sequence points for a CLR method from the symbol file.

Location constraint: This API will fail when called from an IDE component to query information for server-side compiled ASP.NET code, or dynamically compiled code.

This API was introduced in Visual Studio 16 RTM (DkmApiVersion.VS16RTMPreview).

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)

Applies to