System.Diagnostics.SymbolStore.ISymbolWriter Interface

Assembly: Mscorlib.dll
Namespace: System.Diagnostics.SymbolStore
Summary
Represents a symbol writer for managed code.
C# Syntax:
public interface ISymbolWriter
Remarks
The ISymbolWriter interface provides methods that define documents, sequence points, lexical scopes, and variables.
See also:
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

Method: Close()
Summary
Closes ISymbolWriter and commits the symbols to the symbol store.
C# Syntax:
void Close();
Remarks
After this call, ISymbolWriter becomes invalid for further updates.

Return to top


Method: CloseMethod()
Summary
Closes the current method.
C# Syntax:
void CloseMethod();
Remarks
After a method is closed, you cannot define a symbol from within.

Return to top


Method: CloseNamespace()
Summary
Closes the most recent namespace.
C# Syntax:
void CloseNamespace();

Return to top


Method: CloseScope(
   int endOffset
)
Summary
Closes the current lexical scope.
C# Syntax:
void CloseScope(
   int endOffset
);
Parameters:

endOffset

The points past the last instruction in the scope.

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

Return to top


Method: DefineDocument(
   string url,
   Guid language,
   Guid languageVendor,
   Guid documentType
)
Summary
Defines a source document.
C# Syntax:
ISymbolDocumentWriter DefineDocument(
   string url,
   Guid language,
   Guid languageVendor,
   Guid documentType
);
Parameters:

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


Method: DefineField(
   SymbolToken parent,
   string name,
   FieldAttributes attributes,
   byte[] signature,
   SymAddressKind addrKind,
   int addr1,
   int addr2,
   int addr3
)
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
);
Parameters:

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.

Remarks
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


Method: DefineGlobalVariable(
   string name,
   FieldAttributes attributes,
   byte[] signature,
   SymAddressKind addrKind,
   int addr1,
   int addr2,
   int addr3
)
Summary
Defines a single global variable.
C# Syntax:
void DefineGlobalVariable(
   string name,
   FieldAttributes attributes,
   byte[] signature,
   SymAddressKind addrKind,
   int addr1,
   int addr2,
   int addr3
);
Parameters:

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


Method: DefineLocalVariable(
   string name,
   FieldAttributes attributes,
   byte[] signature,
   SymAddressKind addrKind,
   int addr1,
   int addr2,
   int addr3,
   int startOffset,
   int endOffset
)
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
);
Parameters:

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.

Remarks
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


Method: DefineParameter(
   string name,
   ParameterAttributes attributes,
   int sequence,
   SymAddressKind addrKind,
   int addr1,
   int addr2,
   int addr3
)
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
);
Parameters:

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.

Remarks
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


Method: DefineSequencePoints(
   ISymbolDocumentWriter document,
   int[] offsets,
   int[] lines,
   int[] columns,
   int[] endLines,
   int[] endColumns
)
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
);
Parameters:

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.

Remarks
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


Method: Initialize(
   IntPtr emitter,
   string filename,
   bool fFullBuild
)
Summary
Sets the metadata emitter interface to associate with a writer.
C# Syntax:
void Initialize(
   IntPtr emitter,
   string filename,
   bool fFullBuild
);
Parameters:

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.

Remarks
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


Method: OpenMethod(
   SymbolToken method
)
Summary
Opens a method to place symbol information into.
C# Syntax:
void OpenMethod(
   SymbolToken method
);
Parameters:

method

The metadata token for the method to be opened.

Remarks
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


Method: OpenNamespace(
   string name
)
Summary
Opens a new namespace.
C# Syntax:
void OpenNamespace(
   string name
);
Parameters:

name

The name of the new namespace.

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

Return to top


Method: OpenScope(
   int startOffset
)
Summary
Opens a new lexical scope in the current method.
C# Syntax:
int OpenScope(
   int startOffset
);
Parameters:

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.
Remarks
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


Method: SetMethodSourceRange(
   ISymbolDocumentWriter startDoc,
   int startLine,
   int startColumn,
   ISymbolDocumentWriter endDoc,
   int endLine,
   int endColumn
)
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
);
Parameters:

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


Method: SetScopeRange(
   int scopeID,
   int startOffset,
   int endOffset
)
Summary
Defines the offset range for the specified lexical scope.
C# Syntax:
void SetScopeRange(
   int scopeID,
   int startOffset,
   int endOffset
);
Parameters:

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


Method: SetSymAttribute(
   SymbolToken parent,
   string name,
   byte[] data
)
Summary
Defines an attribute when given the attribute name and the attribute value.
C# Syntax:
void SetSymAttribute(
   SymbolToken parent,
   string name,
   byte[] data
);
Parameters:

parent

The metadata token for which the attribute is being defined.

name

The attribute name.

data

The attribute value.

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

Return to top


Method: SetUnderlyingWriter(
   IntPtr underlyingWriter
)
Summary
Sets the underlying ISymUnmanagedWriter (the corresponding unmanaged API) that a managed ISymbolWriter uses to emit symbols.
C# Syntax:
void SetUnderlyingWriter(
   IntPtr underlyingWriter
);
Parameters:

underlyingWriter

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

Remarks
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


Method: SetUserEntryPoint(
   SymbolToken entryMethod
)
Summary
Identifies the user-defined method as the entry point for the current module.
C# Syntax:
void SetUserEntryPoint(
   SymbolToken entryMethod
);
Parameters:

entryMethod

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

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

Return to top


Method: UsingNamespace(
   string fullName
)
Summary
Specifies that the given, fully-qualified namespace name is used within the open lexical scope.
C# Syntax:
void UsingNamespace(
   string fullName
);
Parameters:

fullName

The fully-qualified name of the namespace.

Remarks
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

Copyright (c) 2002 Microsoft Corporation. All rights reserved.