This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!
Emitting Symbolic Information
The Reflection Emit APIs allow symbolic information to be defined for a dynamic module. Symbolic information can be defined using the default symbol writer interface or a caller specified symbol writer interface. The Reflection Emit APIs provide a convenient high-level abstraction of the low-level symbol writer interfaces in System.Diagnostics.SymbolStore.
The caller must express an intention that a dynamic module will contain symbolic information by calling the appropriate method to define the dynamic module. The various options for creating dynamic modules with symbolic information are described in the section Defining a Dynamic Module. It is an error to call a symbol writer method for a dynamic module that has not been created with the intention to contain symbolic information.
Reflection Emit provides the following methods for emitting symbolic information:
- The symbol writer interface associated with a dynamic module can be obtained using ModuleBuilder.GetSymWriter.
- The user entry point for a dynamic module can be defined using ModuleBuilder.SetUserEntryPoint. The user entry point is the method that the user has identified as the entry point rather than the caller generated stubs before the main method.
- Document objects are defined using ModuleBuilder.DefineDocument.
- Custom attributes stored in the symbol store are defined respectively for modules, methods, and constructors using ModuleBuilder.SetSymCustomAttribute, ConstructorBuilder.SetSymCustomAttribute, or ModuleBuilder.SetSymCustomAttribute. These custom attributes are different from the metadata custom attributes defined using the ICustomAttributeBuilder interface.
- Sequence points are identified using ILGenerator.MarkSequencePoint. See the NGWS Runtime Debugging Services specification for a definition of sequence point.
- Lexical scopes are defined using ILGenerator.BeginScope and ILGenerator.EndScope.
- The name of a local variable in a method or a constructor can be set using LocalBuilder.SetLocalSymInfo. Optionally, the lexical scope of the local variable can be specified. A LocalBuilder object is obtained by calling ILGenerator.DeclareLocal.