System.Reflection.Emit.ILGenerator Class

Summary

Generates Microsoft intermediate language (MSIL) instructions.

C# Syntax:

public class ILGenerator

Reflection Emit is thread-safe when using assemblies that were created with the AppDomain.DefineDynamicAssembly method with the Boolean parameter isSynchronized set to true.

MSIL is used as input to a just-in-time (JIT) compiler.

System.Reflection.Emit Namespace

System.Reflection.Emit.ILGenerator Member List:

Public Methods

BeginCatchBlock	Begins a catch block.
BeginExceptFilterBlock	Begins an exception block for a filtered exception.
BeginExceptionBlock	Begins an exception block for a non-filtered exception.
BeginFaultBlock	Begins an exception fault block in the Microsoft intermediate language (MSIL) stream.
BeginFinallyBlock	Begins a finally block in the Microsoft intermediate language (MSIL) instruction stream.
BeginScope	Begins a lexical scope.
DeclareLocal	Declares a local variable.
DefineLabel	Declares a new label.
Emit	Overloaded: Emit(OpCode opcode) Puts the specified instruction onto the stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, byte arg) Puts the specified instruction and character argument onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, ConstructorInfo con) Puts the specified instruction and metadata token for the specified constructor onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, double arg) Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, FieldInfo field) Puts the specified instruction and metadata token for the specified field onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, short arg) Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, int arg) Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, long arg) Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, Label label) Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream and leaves space to include a label when fixes are done.
Emit	Overloaded: Emit(OpCode opcode, Label[] labels) Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream and leaves space to include a label when fixes are done.
Emit	Overloaded: Emit(OpCode opcode, LocalBuilder local) Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the index of the given local variable.
Emit	Overloaded: Emit(OpCode opcode, MethodInfo meth) Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given method.
Emit	Overloaded: Emit(OpCode opcode, sbyte arg) Puts the specified instruction and character argument onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, SignatureHelper signature) Puts the specified instruction and a signature token onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, float arg) Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.
Emit	Overloaded: Emit(OpCode opcode, string str) Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given string.
Emit	Overloaded: Emit(OpCode opcode, Type cls) Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given type.
EmitCall	Puts a call or callvirt instruction onto the Microsoft intermediate language (MSIL) stream.
EmitCalli	Overloaded: EmitCalli(OpCode opcode, CallingConvention unmanagedCallConv, Type returnType, Type[] parameterTypes) Puts a calli instruction using an unmanaged calling convention onto the Microsoft intermediate language (MSIL) stream.
EmitCalli	Overloaded: EmitCalli(OpCode opcode, CallingConventions callingConvention, Type returnType, Type[] parameterTypes, Type[] optionalParameterTypes) Puts a calli instruction using a managed calling convention onto the Microsoft intermediate language (MSIL) stream.
EmitWriteLine	Overloaded: EmitWriteLine(FieldInfo fld) Emits the Microsoft intermediate language (MSIL) necessary to call Console.WriteLine with the given field.
EmitWriteLine	Overloaded: EmitWriteLine(LocalBuilder localBuilder) Emits the Microsoft intermediate language (MSIL) necessary to call Console.WriteLine with the given local variable.
EmitWriteLine	Overloaded: EmitWriteLine(string value) Emits the Microsoft intermediate language (MSIL) to call Console.WriteLine with a string.
EndExceptionBlock	Ends an exception block.
EndScope	Ends a lexical scope.
Equals (inherited from System.Object)	See base class member description: System.Object.Equals Derived from System.Object, the primary base class for all objects.
GetHashCode (inherited from System.Object)	See base class member description: System.Object.GetHashCode Derived from System.Object, the primary base class for all objects.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
MarkLabel	Marks the Microsoft intermediate language (MSIL) stream's current position with the given label.
MarkSequencePoint	Marks a sequence point in the Microsoft intermediate language (MSIL) stream.
ThrowException	Emits an instruction to throw an exception.
ToString (inherited from System.Object)	See base class member description: System.Object.ToString Derived from System.Object, the primary base class for all objects.
UsingNamespace	Specifies the namespace to be used in evaluating locals and watches for the current active lexical scope.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

• System.Object
• System.Reflection.Emit.ILGenerator

System.Reflection.Emit.ILGenerator Member Details

Summary

Begins a catch block.

C# Syntax:

public virtual void BeginCatchBlock(    Type exceptionType );

exceptionType

The Type object that represents the exception.

Exceptions

Exception Type	Condition
ArgumentException	The catch block is within a filtered exception.
ArgumentNullException	exceptionType is null and the exception filter block has not returned a value that indicates that finally blocks should be run until this catch block is located.
NotSupportedException	The Microsoft intermediate language (MSIL) being generated is not currently in an exception block.

Emits a branch instruction to the end of the current exception block.

Note If the filter exception block returns the constant exception_execute_handler (see the documentation for the Common Language Infrastructure Instruction Set), the argument to the BeginCatchBlock is not checked.

Return to top

Summary

Begins an exception block for a filtered exception.

C# Syntax:

public virtual void BeginExceptFilterBlock();

Exceptions

Exception Type	Condition
NotSupportedException	The Microsoft intermediate language (MSIL) being generated is not currently in an exception block.

Emits a branch instruction to the end of the current exception block.

Return to top

Summary

Begins an exception block for a non-filtered exception.

C# Syntax:

public virtual Label BeginExceptionBlock();

Return Value:

The label for the end of the block. This will leave you in the correct place to execute finally blocks or to finish the try.

Creating an exception block records some information, but does not actually emit any Microsoft intermediate language (MSIL) onto the stream.

Return to top

Summary

Begins an exception fault block in the Microsoft intermediate language (MSIL) stream.

C# Syntax:

public virtual void BeginFaultBlock();

Exceptions

Exception Type	Condition
NotSupportedException	The Microsoft intermediate language (MSIL) being generated is not currently in an exception block.

Return to top

Summary

Begins a finally block in the Microsoft intermediate language (MSIL) instruction stream.

C# Syntax:

public virtual void BeginFinallyBlock();

Exceptions

Exception Type	Condition
NotSupportedException	The Microsoft intermediate language (MSIL) being generated is not currently in an exception block.

Return to top

Summary

Begins a lexical scope.

C# Syntax:

public virtual void BeginScope();

This method is used to emit symbolic information. Local variables declared after ILGenerator.BeginScope is scoped till corresponding ILGenerator.EndScope is called.

Return to top

Summary

Declares a local variable.

C# Syntax:

public LocalBuilder DeclareLocal(    Type localType );

localType

The Type of the local variable.

Return Value:

The declared local variable.

Exceptions

Exception Type	Condition
ArgumentNullException	localType is null.
InvalidOperationException	The containing type has been created with TypeBuilder.CreateType.

Return to top

Summary

Declares a new label.

C# Syntax:

public virtual Label DefineLabel();

Return Value:

Returns a new label that can be used as a token for branching.

In order to set the position of the label within the stream, you must call ILGenerator.MarkLabel.

This is just a token and does not yet represent any particular location within the stream.

Return to top

Summary

Puts the specified instruction onto the stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode );

opcode

The Microsoft intermediate language (MSIL) instruction to be put onto the stream. Defined in the OpCodes enumeration.

If the opcode requires an argument, the caller must ensure that the argument length matches the length of the declared parameter. Otherwise, results will be unpredictable. For example, if the Emit instruction requires a 2-byte operand and the caller supplies a 4-byte operand, the runtime will emit two additional bytes to the instruction stream. These extra bytes will be Opcodes.Nop instructions. The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction and character argument onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    byte arg );

opcode

The Microsoft intermediate language (MSIL) instruction to be put onto the stream.

arg

The character argument pushed onto the stream immediately after the instruction.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction and metadata token for the specified constructor onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    ConstructorInfo con );

opcode

The Microsoft intermediate language (MSIL) instruction to be emitted onto the stream.

con

A ConstructorInfo representing a constructor.

The instruction values are defined in the OpCodes enumeration. The location of con is recorded so that the instruction stream can be patched if necessary when persisting the module to a PE.

Return to top

Summary

Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    double arg );

opcode

The Microsoft intermediate language (MSIL) instruction to be put onto the stream. Defined in the OpCodes enumeration.

arg

The numerical argument pushed onto the stream immediately after the instruction.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction and metadata token for the specified field onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    FieldInfo field );

opcode

The Microsoft intermediate language (MSIL) instruction to be emitted onto the stream.

field

A FieldInfo representing a field.

The instruction values are defined in the OpCodes enumeration. The location of field is recorded so that the instruction stream can be patched if necessary when persisting the module to a portable executable (PE).

Return to top

Summary

Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    short arg );

opcode

The Microsoft intermediate language (MSIL) instruction to be emitted onto the stream.

arg

The Int argument pushed onto the stream immediately after the instruction.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    int arg );

opcode

The Microsoft intermediate language (MSIL) instruction to be put onto the stream.

arg

The numerical argument pushed onto the stream immediately after the instruction.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    long arg );

opcode

The Microsoft intermediate language (MSIL) instruction to be put onto the stream.

arg

The numerical argument pushed onto the stream immediately after the instruction.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream and leaves space to include a label when fixes are done.

C# Syntax:

public virtual void Emit(    OpCode opcode,    Label label );

opcode

The Microsoft intermediate language (MSIL) instruction to be emitted onto the stream.

label

The label to which to branch from this location.

The instruction values are defined in the OpCodes enumeration. Labels are created using ILGenerator.DefineLabel and their location within the stream is fixed by using ILGenerator.MarkLabel. If a single-byte instruction is used, the label can represent a jump of at most 127 bytes along the stream.instruction must represent a branch instruction. Since branches are relative instructions, label will be replaced with the correct offset to branch during the fixup process.

Return to top

Summary

Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream and leaves space to include a label when fixes are done.

C# Syntax:

public virtual void Emit(    OpCode opcode,    Label[] labels );

opcode

The Microsoft intermediate language (MSIL) instruction to be emitted onto the stream.

labels

The array of label objects to which to branch from this location. All of the labels will be used.

Emits a switch table.

The instruction values are defined in the OpCodes enumeration.

Labels are created using ILGenerator.DefineLabel and their location within the stream is fixed by using ILGenerator.MarkLabel. If a single-byte instruction is used, the label can represent a jump of at most 127 bytes along the stream.instruction must represent a branch instruction. Since branches are relative instructions, label will be replaced with the correct offset to branch during the fixup process.

Return to top

Summary

Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the index of the given local variable.

C# Syntax:

public virtual void Emit(    OpCode opcode,    LocalBuilder local );

opcode

The MSIL instruction to be emitted onto the stream.

local

A local variable.

Exceptions

Exception Type	Condition
ArgumentException	local 's parent method does not match the method associated with this ILGenerator.
ArgumentNullException	local is null.
InvalidOperationException	instruction is a single-byte instruction and local represents a local with an index of greater than Byte.MaxValue.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given method.

C# Syntax:

public virtual void Emit(    OpCode opcode,    MethodInfo meth );

opcode

The MSIL instruction to be emitted onto the stream.

meth

A MethodInfo representing a method.

Exceptions

Exception Type	Condition
ArgumentNullException	meth is null.

The instruction values are defined in the OpCodes enumeration. The location of meth is recorded so that the instruction stream can be patched if necessary when persisting the module to a portable executable file.

Return to top

Summary

Puts the specified instruction and character argument onto the Microsoft intermediate language (MSIL) stream of instructions.

This member is not CLS Compliant

C# Syntax:

[CLSCompliant(false)] public void Emit(    OpCode opcode,    sbyte arg );

opcode

The Microsoft intermediate language (MSIL) instruction to be put onto the stream.

arg

The character argument pushed onto the stream immediately after the instruction.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction and a signature token onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    SignatureHelper signature );

opcode

The Microsoft intermediate language (MSIL) instruction to be emitted onto the stream.

signature

A helper for constructing a signature token.

Exceptions

Exception Type	Condition
ArgumentNullException	signature is null.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction and numerical argument onto the Microsoft intermediate language (MSIL) stream of instructions.

C# Syntax:

public virtual void Emit(    OpCode opcode,    float arg );

opcode

The Microsoft intermediate language (MSIL) instruction to be put onto the stream.

arg

The Single argument pushed onto the stream immediately after the instruction.

The instruction values are defined in the OpCodes enumeration.

Return to top

Summary

Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given string.

C# Syntax:

public virtual void Emit(    OpCode opcode,    string str );

opcode

The MSIL instruction to be emitted onto the stream.

str

The String to be emitted.

The instruction values are defined in the OpCodes enumeration. The location of str is recorded for future fixups if the module is persisted to a portable executable (PE).

Return to top

Summary

Puts the specified instruction onto the Microsoft intermediate language (MSIL) stream followed by the metadata token for the given type.

C# Syntax:

public virtual void Emit(    OpCode opcode,    Type cls );

opcode

The MSIL instruction to be put onto the stream.

cls

A Type.

Exceptions

Exception Type	Condition
ArgumentNullException	cls is null.

The instruction values are defined in the OpCodes enumeration. The location of cls is recorded so that the token can be patched if necessary when persisting the module to a portable executable (PE).

Return to top

Summary

Puts a call or callvirt instruction onto the Microsoft intermediate language (MSIL) stream.

C# Syntax:

public void EmitCall(    OpCode opcode,    MethodInfo methodInfo,    Type[] optionalParameterTypes );

opcode

The MSIL instruction to be emitted onto the stream.

methodInfo

The method to be called.

optionalParameterTypes

The types of the optional arguments if the method is a varargs method.

Exceptions

Exception Type	Condition
ArgumentNullException	methodInfo is null.
InvalidOperationException	The calling convention for the method is not varargs but optional parameter types are supplied.

This method cannot be used to call a constructor. Instead, use the overloaded ILGenerator.Emit method that takes a ConstructorInfo argument.

Return to top

Summary

Puts a calli instruction using an unmanaged calling convention onto the Microsoft intermediate language (MSIL) stream.

C# Syntax:

public void EmitCalli(    OpCode opcode,    CallingConvention unmanagedCallConv,    Type returnType,    Type[] parameterTypes );

opcode

The MSIL instruction to be emitted onto the stream.

unmanagedCallConv

The unmanaged calling convention to be used.

returnType

The Type of the result.

parameterTypes

The types of the required arguments to the instruction.

Return to top

Summary

Puts a calli instruction using a managed calling convention onto the Microsoft intermediate language (MSIL) stream.

C# Syntax:

public void EmitCalli(    OpCode opcode,    CallingConventions callingConvention,    Type returnType,    Type[] parameterTypes,    Type[] optionalParameterTypes );

opcode

The MSIL instruction to be emitted onto the stream.

callingConvention

The managed calling convention to be used.

returnType

The Type of the result.

parameterTypes

The types of the required arguments to the instruction.

optionalParameterTypes

The types of the optional arguments for vararg calls.

Return to top

Summary

Emits the Microsoft intermediate language (MSIL) necessary to call Console.WriteLine with the given field.

C# Syntax:

public virtual void EmitWriteLine(    FieldInfo fld );

fld

The field whose value is to be written to the console.

Exceptions

Exception Type	Condition
ArgumentException	There is no TextWriter.WriteLine method for the type of the specified field.
ArgumentNullException	fld is null.
NotSupportedException	The type of the field is TypeBuilder or EnumBuilder.

Return to top

Summary

Emits the Microsoft intermediate language (MSIL) necessary to call Console.WriteLine with the given local variable.

C# Syntax:

public virtual void EmitWriteLine(    LocalBuilder localBuilder );

localBuilder

The local variable whose value is to be written to the console.

Exceptions

Exception Type	Condition
ArgumentException	The type of localBuilder is not supported (TypeBuilder, for example).

It is an error to call EmitWriteLine with a LocalBuilder which is not of one of the types for which Console.WriteLine implements overloads.

Return to top

Summary

Emits the Microsoft intermediate language (MSIL) to call Console.WriteLine with a string.

C# Syntax:

public virtual void EmitWriteLine(    string value );

value

The string to be printed.

The string must have already been defined.

Return to top

Summary

Ends an exception block.

C# Syntax:

public virtual void EndExceptionBlock();

Exceptions

Exception Type	Condition
InvalidOperationException	The end exception block occurs in an unexpected place in the code stream.
NotSupportedException	The Microsoft intermediate language (MSIL) being generated is not currently in an exception block.

Return to top

Summary

Ends a lexical scope.

C# Syntax:

public virtual void EndScope();

This method is used to emit symbolic information. It is used with ILGenerator.BeginScope.

Return to top

Inherited
See base class member description: System.Object.Equals

C# Syntax:

public virtual bool Equals(    object obj );

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.Finalize

C# Syntax:

~ILGenerator();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetHashCode

C# Syntax:

public virtual int GetHashCode();

For more information on members inherited from System.Object click on the link above.

Return to top

Inherited
See base class member description: System.Object.GetType

C# Syntax:

public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Marks the Microsoft intermediate language (MSIL) stream's current position with the given label.

C# Syntax:

public virtual void MarkLabel(    Label loc );

loc

The label for which to set an index.

Exceptions

Exception Type	Condition
ArgumentException	loc represents an invalid index into the label array. -or- An index for loc has already been defined.

A label cannot be defined more than once.

Return to top

Summary

Marks a sequence point in the Microsoft intermediate language (MSIL) stream.

C# Syntax:

public virtual void MarkSequencePoint(    ISymbolDocumentWriter document,    int startLine,    int startColumn,    int endLine,    int endColumn );

document

The document for which the sequence point is being defined.

startLine

The line where the sequence point begins.

startColumn

The column in the line where the sequence point begins.

endLine

The line where the sequence point ends.

endColumn

The column in the line where the sequence point ends.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	startLine or endLine is <= 0.

Line numbers are indexed from 1. Columns are indexed from 0.

The symbolic information normally includes at least one Microsoft intermediate language (MSIL) offset for each source line. When the just-in-time (JIT) compiler is about to compile a method, it asks the profiling services for a list of MSIL offsets that should be preserved. These MSIL offsets are called sequence points.

Return to top

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:

protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Emits an instruction to throw an exception.

C# Syntax:

public virtual void ThrowException(    Type excType );

excType

The class of the type of exception to throw.

Exceptions

Exception Type	Condition
ArgumentException	excType is not the Exception class or a derived class of Exception. -or- The type does not have a default constructor.
ArgumentNullException	excType is null.

Return to top

Inherited
See base class member description: System.Object.ToString

C# Syntax:

public virtual string ToString();

For more information on members inherited from System.Object click on the link above.

Return to top

Summary

Specifies the namespace to be used in evaluating locals and watches for the current active lexical scope.

C# Syntax:

public void UsingNamespace(    string usingNamespace );

usingNamespace

The namespace to be used in evaluating locals and watches for the current active lexical scope

Exceptions

Exception Type	Condition
ArgumentException	Length of usingNamespace is zero.
ArgumentNullException	usingNamespace is null.

Return to top

Top of page