InstructionEncoder Struct

Definition

Namespace:

System.Reflection.Metadata.Ecma335

Assembly:

System.Reflection.Metadata.dll

Source:

InstructionEncoder.cs

Encodes Common Intermediate Language (CIL) instructions.

public value class InstructionEncoder

public readonly struct InstructionEncoder

type InstructionEncoder = struct

Public Structure InstructionEncoder

Inheritance

Object

ValueType

InstructionEncoder

Examples

This example shows how to emit a method body using InstructionEncoder:

// The following code emits a method body similar to this C# code:

/*public static double CalcRectangleArea(double length, double width)
{
    if (length < 0.0)
    {
        throw new ArgumentOutOfRangeException("length");
    }

    if (width < 0.0)
    {
        throw new ArgumentOutOfRangeException("width");
    }

    return length * width;
}*/

private static InstructionEncoder EmitMethodBody(MetadataBuilder metadata, AssemblyReferenceHandle corlibAssemblyRef)
{
    var codeBuilder = new BlobBuilder();
    var encoder = new InstructionEncoder(codeBuilder, new ControlFlowBuilder());

    // Get a reference to the System.ArgumentOutOfRangeException type
    TypeReferenceHandle typeRefHandle = metadata.AddTypeReference(
    corlibAssemblyRef,
    metadata.GetOrAddString("System"),
    metadata.GetOrAddString("ArgumentOutOfRangeException"));

    // Signature: .ctor(string)
    var ctorSignature = new BlobBuilder();

    new BlobEncoder(ctorSignature).
        MethodSignature(isInstanceMethod: true).
        Parameters(1, returnType => returnType.Void(), parameters => parameters.AddParameter().Type().String());

    BlobHandle ctorBlobIndex = metadata.GetOrAddBlob(ctorSignature);

    // Get a reference to the System.ArgumentOutOfRangeException constructor
    MemberReferenceHandle ctorMemberRef = metadata.AddMemberReference(
        typeRefHandle,
        metadata.GetOrAddString(".ctor"),
        ctorBlobIndex);

    LabelHandle label1 = encoder.DefineLabel();
    LabelHandle label2 = encoder.DefineLabel();

    // ldarg.0
    encoder.OpCode(ILOpCode.Ldarg_0);

    // ldc.r8 0
    encoder.LoadConstantR8(0);

    // bge.un.s LABEL1
    encoder.Branch(ILOpCode.Bge_un_s, label1);

    // ldstr "length"
    encoder.LoadString(metadata.GetOrAddUserString("length"));

    // newobj instance void [System.Runtime]System.ArgumentOutOfRangeException::.ctor(string)
    encoder.OpCode(ILOpCode.Newobj);
    encoder.Token(ctorMemberRef);

    // throw
    encoder.OpCode(ILOpCode.Throw);

    // LABEL1: ldarg.1
    encoder.MarkLabel(label1);
    encoder.OpCode(ILOpCode.Ldarg_1);

    // ldc.r8 0
    encoder.LoadConstantR8(0);

    // bge.un.s LABEL2
    encoder.Branch(ILOpCode.Bge_un_s, label2);

    // ldstr "width"
    encoder.LoadString(metadata.GetOrAddUserString("width"));

    // newobj instance void [System.Runtime]System.ArgumentOutOfRangeException::.ctor(string)
    encoder.OpCode(ILOpCode.Newobj);
    encoder.Token(ctorMemberRef);

    // throw
    encoder.OpCode(ILOpCode.Throw);

    // LABEL2: ldarg.0
    encoder.MarkLabel(label2);
    encoder.OpCode(ILOpCode.Ldarg_0);

    // ldarg.1
    encoder.OpCode(ILOpCode.Ldarg_1);

    // mul
    encoder.OpCode(ILOpCode.Mul);

    // ret
    encoder.OpCode(ILOpCode.Ret);

    return encoder;
}

Remarks

The InstructionEncoder class is used to emit CIL instructions that make up a method body. For a complete example of emitting a method, see the MetadataBuilder class documentation.

Constructors

InstructionEncoder(BlobBuilder, ControlFlowBuilder)

Creates an encoder backed by code and control-flow builders.

Properties

CodeBuilder	Underlying builder where encoded instructions are written to.
ControlFlowBuilder	Builder tracking labels, branches and exception handlers.
Offset	Offset of the next encoded instruction.

Methods

Branch(ILOpCode, LabelHandle)	Encodes a branch instruction.
Call(EntityHandle)	Encodes call instruction and its operand.
Call(MemberReferenceHandle)	Encodes call instruction and its operand.
Call(MethodDefinitionHandle)	Encodes call instruction and its operand.
Call(MethodSpecificationHandle)	Encodes call instruction and its operand.
CallIndirect(StandaloneSignatureHandle)	Encodes calli instruction and its operand.
DefineLabel()	Defines a label that can later be used to mark and refer to a location in the instruction stream.
LoadArgument(Int32)	Encodes argument load instruction.
LoadArgumentAddress(Int32)	Encodes argument address load instruction.
LoadConstantI4(Int32)	Encodes Int32 constant load instruction.
LoadConstantI8(Int64)	Encodes Int64 constant load instruction.
LoadConstantR4(Single)	Encodes Single constant load instruction.
LoadConstantR8(Double)	Encodes Double constant load instruction.
LoadLocal(Int32)	Encodes local variable load instruction.
LoadLocalAddress(Int32)	Encodes local variable address load instruction.
LoadString(UserStringHandle)	Encodes ldstr instruction and its operand.
MarkLabel(LabelHandle)	Associates specified label with the current IL offset.
OpCode(ILOpCode)	Encodes specified op-code.
StoreArgument(Int32)	Encodes argument store instruction.
StoreLocal(Int32)	Encodes local variable store instruction.
Switch(Int32)	Starts encoding a switch instruction.
Token(EntityHandle)	Encodes a token.
Token(Int32)	Encodes a token.