Overview
Debugging symbols are information that allows binding MSIL
instructions with the source code. Debugging symbols are stored
in *.pdb (program database) files and are
automatically loaded by PostSharp when the program database is
located in the same directory as the module.
PostSharp uses the System.Diagnostics.SymbolStore
namespace to retrieve symbols.
Local variable symbols
In pure MSIL, local variables do not have names but only ordinals (a unique number identifying the local variable).
Local variables can be assigned to names inside regions of code called lexical scopes. MSIL allows the same local variable to be assigned to different names in different scopes. Lexical scopes are implemented in PostSharp by the InstructionBlock class. The association between a local variable and a name is encapsulated by the LocalVariableSymbol class.
When you define a new variable, the recommended approach is to
use the DefineLocalVariable method of the InstructionBlock
class.
Symbol sequence points
Symbol sequence points allow to map a region in MSIL instructions to a region in the source code. Symbol sequence points (SymbolSequencePoint) may be inserted between MSIL instructions. The presence of a symbol sequence point before an instruction means that all instructions between this symbol sequence point and the next symbol sequence point are mapped to the region of code indicated by the SymbolSequencePoint class.
The InstructionReader.CurrentInstruction.SymbolSequencePoint
property contains the sequence point that is immediatelybefore the current instruction of an instruction reader.
This property is null if there is no sequence point
just before the current instruction.
The InstructionReader.CurrentInstruction.LastSymbolSequencePoint property contains the last seen sequence. It gives the region of the source code to which the current instruction belong.
Symbol sequence points can be emitted to an instruction writer
using the
EmitSymbolSequencePoint method.
Hidden instructions
If you inject instructions in user code and want to specify that these instructions are not mapped to any source code, you should emit the SymbolSequencePoint.Hidden element. The debugger will simple step through these instructions and never ask for source code.