System.Diagnostics.SymbolStore.ISymbolWriter Interface

Summary

Represents a symbol writer for managed code.

C# Syntax:

public interface ISymbolWriter

The ISymbolWriter interface provides methods that define documents, sequence points, lexical scopes, and variables.

System.Diagnostics.SymbolStore Namespace

System.Diagnostics.SymbolStore.ISymbolWriter Member List:

Public Methods

Close	Closes ISymbolWriter and commits the symbols to the symbol store.
CloseMethod	Closes the current method.
CloseNamespace	Closes the most recent namespace.
CloseScope	Closes the current lexical scope.
DefineDocument	Defines a source document.
DefineField	Defines a field in a type or a global field.
DefineGlobalVariable	Defines a single global variable.
DefineLocalVariable	Defines a single variable in the current lexical scope.
DefineParameter	Defines a single parameter in the current method. The type of each parameter is taken from its position within the signature of the method.
DefineSequencePoints	Defines a group of sequence points within the current method.
Initialize	Sets the metadata emitter interface to associate with a writer.
OpenMethod	Opens a method to place symbol information into.
OpenNamespace	Opens a new namespace.
OpenScope	Opens a new lexical scope in the current method.
SetMethodSourceRange	Specifies the true start and end of a method within a source file. Use ISymbolWriter.SetMethodSourceRange to specify the extent of a method, independent of the sequence points that exist within the method.
SetScopeRange	Defines the offset range for the specified lexical scope.
SetSymAttribute	Defines an attribute when given the attribute name and the attribute value.
SetUnderlyingWriter	Sets the underlying ISymUnmanagedWriter (the corresponding unmanaged API) that a managed ISymbolWriter uses to emit symbols.
SetUserEntryPoint	Identifies the user-defined method as the entry point for the current module.
UsingNamespace	Specifies that the given, fully-qualified namespace name is used within the open lexical scope.

System.Diagnostics.SymbolStore.ISymbolWriter Member Details

Summary

Closes ISymbolWriter and commits the symbols to the symbol store.

C# Syntax:

void Close();

After this call, ISymbolWriter becomes invalid for further updates.

Return to top

Summary

Closes the current method.

C# Syntax:

void CloseMethod();

After a method is closed, you cannot define a symbol from within.

Return to top

Summary

Closes the most recent namespace.

C# Syntax:

void CloseNamespace();

Return to top

Summary

Closes the current lexical scope.

C# Syntax:

void CloseScope(    int endOffset );

endOffset

The points past the last instruction in the scope.

After a scope is closed, you cannot define a variable from within.

Return to top

Summary

Defines a source document.

C# Syntax:

ISymbolDocumentWriter DefineDocument(    string url,    Guid language,    Guid languageVendor,    Guid documentType );

url

The URL that identifies the document.

language

The document language. This parameter can be null.

languageVendor

The identity of the vendor for the document language. This parameter can be null.

documentType

The type of the document. This parameter can be null.

Return Value:

The ISymbolDocumentWriter object that represents the document.

Return to top

Summary

Defines a field in a type or a global field.

C# Syntax:

void DefineField(    SymbolToken parent,    string name,    FieldAttributes attributes,    byte[] signature,    SymAddressKind addrKind,    int addr1,    int addr2,    int addr3 );

parent

The metadata type or method token.

name

The field name.

attributes

The field attributes specified using the FieldAttributes enumerator.

signature

The field signature.

addrKind

The address types for addr1 and addr2 using SymAddressKind.

addr1

The first address for the field specification.

addr2

The second address for the field specification.

addr3

The third address for the field specification.

The ISymbolWriter.DefineField method defines a single variable that is not within a method using specified fields in classes, bit fields, and so on.

Return to top

Summary

Defines a single global variable.

C# Syntax:

void DefineGlobalVariable(    string name,    FieldAttributes attributes,    byte[] signature,    SymAddressKind addrKind,    int addr1,    int addr2,    int addr3 );

name

The global variable name.

attributes

The global variable attributes specified using the FieldAttributes enumerator.

signature

The global variable signature.

addrKind

The address types for addr1, addr2, and addr3 using SymAddressKind.

addr1

The first address for the global variable specification.

addr2

The second address for the global variable specification.

addr3

The third address for the global variable specification.

Return to top

Summary

Defines a single variable in the current lexical scope.

C# Syntax:

void DefineLocalVariable(    string name,    FieldAttributes attributes,    byte[] signature,    SymAddressKind addrKind,    int addr1,    int addr2,    int addr3,    int startOffset,    int endOffset );

name

The local variable name.

attributes

The local variable attributes specified using the FieldAttributes enumerator.

signature

The local variable signature.

addrKind

The address types for addr1, addr2, and addr3 using SymAddressKind.

addr1

The first address for the local variable specification.

addr2

The second address for the local variable specification.

addr3

The third address for the local variable specification.

startOffset

The start offset for the variable. If zero, this parameter is ignored and the variable is defined throughout the entire scope. If nonzero, it falls within the offsets of the current scope.

endOffset

The end offset for the variable. If zero, this parameter is ignored and the variable is defined throughout the entire scope. If nonzero, it falls within the offsets of the current scope.

The startOffset and endOffset parameters are optional. If their value is zero, they are ignored and the variable is defined throughout the entire scope. If their value is nonzero, they fall within the offsets of the current scope.

You can call ISymbolWriter.DefineLocalVariable multiple times for a variable of the same name that occurs multiple times in different offset ranges throughout a scope. (In this case, start and end offsets must not overlap.)

Return to top

Summary

Defines a single parameter in the current method. The type of each parameter is taken from its position within the signature of the method.

C# Syntax:

void DefineParameter(    string name,    ParameterAttributes attributes,    int sequence,    SymAddressKind addrKind,    int addr1,    int addr2,    int addr3 );

name

The parameter name.

attributes

The parameter attributes specified using the ParameterAttributes enumerator.

sequence

The parameter signature.

addrKind

The address types for addr1, addr2, and addr3 using SymAddressKind.

addr1

The first address for the parameter specification.

addr2

The second address for the parameter specification.

addr3

The third address for the parameter specification.

If parameters are defined in the metadata for a given method, you do not have to define them again with calls to this method. Symbol readers need to check for these in the normal metadata first, then fall back to the symbol store.

Return to top

Summary

Defines a group of sequence points within the current method.

C# Syntax:

void DefineSequencePoints(    ISymbolDocumentWriter document,    int[] offsets,    int[] lines,    int[] columns,    int[] endLines,    int[] endColumns );

document

The document object for which the sequence points are being defined.

offsets

The sequence point offsets measured from the beginning of methods.

lines

The document lines for the sequence points.

columns

The document positions for the sequence points.

endLines

The document end lines for the sequence points.

endColumns

The document end positions for the sequence points.

Each line and each column defines the start of a statement within a method. The arrays should be sorted in the increasing order of offsets. The offset is always the offset from the start of the method, in bytes.

Return to top

Summary

Sets the metadata emitter interface to associate with a writer.

C# Syntax:

void Initialize(    IntPtr emitter,    string filename,    bool fFullBuild );

emitter

The metadata emitter interface.

filename

The file name for which the debugging symbols are written. Some writers require a file name, while others do not. If a file name is specified for a writer that does not use file names, this parameter is ignored.

fFullBuild

true indicates that this is a full rebuild; false indicates an incremental compilation.

ISymbolWriter.Initialize also sets the output file name where the debugging symbols are written. This method can be called only once and must be called before any other writer methods are called.

Return to top

Summary

Opens a method to place symbol information into.

C# Syntax:

void OpenMethod(    SymbolToken method );

method

The metadata token for the method to be opened.

The specified method becomes the current method for calls to define sequence points, parameters, and lexical scopes. There is an implicit lexical scope around the entire method. Reopening a method that has been previously closed erases any previously defined symbols for the method.

Return to top

Summary

Opens a new namespace.

C# Syntax:

void OpenNamespace(    string name );

name

The name of the new namespace.

Call this method before defining methods or variables that exist within a namespace. Namespaces can be nested.

Return to top

Summary

Opens a new lexical scope in the current method.

C# Syntax:

int OpenScope(    int startOffset );

startOffset

The offset in bytes from the beginning of the method to the first instruction in the lexical scope.

Return Value:

An opaque scope identifier that can be used with ISymbolWriter.SetScopeRange to define the start and end offsets of a scope at a later time. In this case, the offsets passed to ISymbolWriter.OpenScope and ISymbolWriter.CloseScope are ignored. A scope identifier is valid only in the current method.

This scope becomes the new current scope and is pushed onto a stack of scopes. Scopes must form a hierarchy. Siblings are not allowed to overlap.

Scope identifiers are only valid in the current method.

Return to top

Summary

Specifies the true start and end of a method within a source file. Use ISymbolWriter.SetMethodSourceRange to specify the extent of a method, independent of the sequence points that exist within the method.

C# Syntax:

void SetMethodSourceRange(    ISymbolDocumentWriter startDoc,    int startLine,    int startColumn,    ISymbolDocumentWriter endDoc,    int endLine,    int endColumn );

startDoc

The document containing the starting position.

startLine

The starting line number.

startColumn

The starting column.

endDoc

The document containing the ending position.

endLine

The ending line number.

endColumn

The ending column number.

Return to top

Summary

Defines the offset range for the specified lexical scope.

C# Syntax:

void SetScopeRange(    int scopeID,    int startOffset,    int endOffset );

scopeID

The identifier of the lexical scope.

startOffset

The byte offset of the beginning of the lexical scope.

endOffset

The byte offset of the end of the lexical scope.

Return to top

Summary

Defines an attribute when given the attribute name and the attribute value.

C# Syntax:

void SetSymAttribute(    SymbolToken parent,    string name,    byte[] data );

parent

The metadata token for which the attribute is being defined.

name

The attribute name.

data

The attribute value.

The ISymbolWriter.SetSymAttribute method is only associated with symbolic information and is not a metadata custom attribute.

Return to top

Summary

Sets the underlying ISymUnmanagedWriter (the corresponding unmanaged API) that a managed ISymbolWriter uses to emit symbols.

C# Syntax:

void SetUnderlyingWriter(    IntPtr underlyingWriter );

underlyingWriter

An IntPtr type pointer to code that is the underlying writer.

The underlying ISymUnmanagedWriter (the corresponding unmanaged API) interface represents a symbol writer for managed code. The interface provides methods to define documents, sequence points, lexical scopes, and variables.

Return to top

Summary

Identifies the user-defined method as the entry point for the current module.

C# Syntax:

void SetUserEntryPoint(    SymbolToken entryMethod );

entryMethod

The metadata token for the method that is the user entry point.

This is normally your main method, rather than compiler-generated stubs before the main method.

Return to top

Summary

Specifies that the given, fully-qualified namespace name is used within the open lexical scope.

C# Syntax:

void UsingNamespace(    string fullName );

fullName

The fully-qualified name of the namespace.

Closing the current scope prevents this scope from using the namespace. The namespace remains in use in all scopes that inherit from the current open scope.

Return to top

Top of page