Class CilInstructionCollection

Namespace

AsmResolver.DotNet.Code.Cil

Assembly

AsmResolver.DotNet.dll

Represents a collection of CIL instructions found in a method body.

public class CilInstructionCollection : IList<CilInstruction>, ICollection<CilInstruction>, IReadOnlyList<CilInstruction>, IReadOnlyCollection<CilInstruction>, IEnumerable<CilInstruction>, IEnumerable

Inheritance

object

CilInstructionCollection

Implements

IList<CilInstruction>

ICollection<CilInstruction>

IReadOnlyList<CilInstruction>

IReadOnlyCollection<CilInstruction>

IEnumerable<CilInstruction>

IEnumerable

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

CilInstructionCollection(CilMethodBody)

Creates a new collection of CIL instructions stored in a method body.

public CilInstructionCollection(CilMethodBody body)

Parameters

body CilMethodBody

The method body that owns the collection.

Properties

Count

public int Count { get; }

Property Value

int

EndLabel

Gets the label indicating the end of the CIL code stream.

public ICilLabel EndLabel { get; }

Property Value

ICilLabel

Remarks

This label does not point to the beginning of an instruction. The offset of this label is equal to the last instruction's offset + its size.

IsReadOnly

public bool IsReadOnly { get; }

Property Value

bool

this[int]

public CilInstruction this[int index] { get; set; }

Parameters

index int

Property Value

CilInstruction

Owner

Gets the method body that owns the collection of CIL instructions.

public CilMethodBody Owner { get; }

Property Value

CilMethodBody

Size

Gets the size in bytes of the collection.

public int Size { get; }

Property Value

int

Methods

Add(CilInstruction)

public void Add(CilInstruction item)

Parameters

item CilInstruction

Add(CilOpCode)

Verifies and adds an instruction to the end of the collection.

public CilInstruction Add(CilOpCode code)

Parameters

code CilOpCode

The code.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation requires an operand.

Add(CilOpCode, CilLocalVariable)

Verifies and adds a instruction to the end of the collection that references a local variable.

public CilInstruction Add(CilOpCode code, CilLocalVariable variable)

Parameters

code CilOpCode

The opcode.

variable CilLocalVariable

The referenced variable.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a variable.

ArgumentNullException

Occurs when variable is null.

Add(CilOpCode, Parameter)

Verifies and adds a instruction to the end of the collection that references a parameter.

public CilInstruction Add(CilOpCode code, Parameter parameter)

Parameters

code CilOpCode

The opcode.

parameter Parameter

The referenced parameter.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a parameter.

ArgumentNullException

Occurs when parameter is null.

Add(CilOpCode, IFieldDescriptor)

Verifies and adds an instruction to the end of the collection that references a field.

public CilInstruction Add(CilOpCode code, IFieldDescriptor field)

Parameters

code CilOpCode

The field opcode.

field IFieldDescriptor

The field referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a field opcode.

ArgumentNullException

Occurs when field is null.

Add(CilOpCode, IMetadataMember)

Verifies and adds an instruction to the end of the collection that references a metadata member.

public CilInstruction Add(CilOpCode code, IMetadataMember member)

Parameters

code CilOpCode

The method opcode.

member IMetadataMember

The member referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a member opcode.

ArgumentNullException

Occurs when member is null.

Add(CilOpCode, IMethodDescriptor)

Verifies and adds an instruction to the end of the collection that references a method.

public CilInstruction Add(CilOpCode code, IMethodDescriptor method)

Parameters

code CilOpCode

The method opcode.

method IMethodDescriptor

The method referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a method opcode.

ArgumentNullException

Occurs when method is null.

Add(CilOpCode, ITypeDefOrRef)

Verifies and adds an instruction to the end of the collection that references a type.

public CilInstruction Add(CilOpCode code, ITypeDefOrRef type)

Parameters

code CilOpCode

The type opcode.

type ITypeDefOrRef

The type referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a type opcode.

ArgumentNullException

Occurs when type is null.

Add(CilOpCode, MemberReference)

Verifies and adds an instruction to the end of the collection that references a member.

public CilInstruction Add(CilOpCode code, MemberReference member)

Parameters

code CilOpCode

The member opcode.

member MemberReference

The member referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation does not match with the provided member reference.

ArgumentNullException

Occurs when member is null.

Add(CilOpCode, StandAloneSignature)

Verifies and adds a instruction to the end of the collection that references a standalone signature referencing a method signature in the blob stream.

public CilInstruction Add(CilOpCode code, StandAloneSignature signature)

Parameters

code CilOpCode

The opcode.

signature StandAloneSignature

The referenced signature.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a standalone signature.

Add(CilOpCode, ICilLabel)

Verifies and adds a branch instruction to the end of the collection.

public CilInstruction Add(CilOpCode code, ICilLabel label)

Parameters

code CilOpCode

The branch opcode.

label ICilLabel

The label referenced by the branch instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a branch opcode.

ArgumentNullException

Occurs when label is null.

Add(CilOpCode, params ICilLabel[])

Verifies and adds a switch instruction to the end of the collection.

public CilInstruction Add(CilOpCode code, params ICilLabel[] labels)

Parameters

code CilOpCode

The switch opcode.

labels ICilLabel[]

The labels referenced by the switch instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a branch opcode.

ArgumentNullException

Occurs when labels is null.

Add(CilOpCode, MetadataToken)

Verifies and adds a instruction to the end of the collection that references a metadata member by its token.

public CilInstruction Add(CilOpCode code, MetadataToken token)

Parameters

code CilOpCode

The opcode.

token MetadataToken

The token of the referenced member.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a metadata member.

ArgumentOutOfRangeException

Occurs when the provided token is not valid in a CIL stream.

Add(CilOpCode, IEnumerable<ICilLabel>)

Verifies and adds a switch instruction to the end of the collection.

public CilInstruction Add(CilOpCode code, IEnumerable<ICilLabel> labels)

Parameters

code CilOpCode

The switch opcode.

labels IEnumerable<ICilLabel>

The labels referenced by the switch instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a branch opcode.

ArgumentNullException

Occurs when labels is null.

Add(CilOpCode, double)

Verifies and adds a instruction to the end of the collection that references a float64 constant.

public CilInstruction Add(CilOpCode code, double constant)

Parameters

code CilOpCode

The opcode.

constant double

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a float64 constant.

Add(CilOpCode, int)

Verifies and adds a instruction to the end of the collection that pushes an integer constant.

public CilInstruction Add(CilOpCode code, int constant)

Parameters

code CilOpCode

The opcode.

constant int

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing an integer constant.

Add(CilOpCode, long)

Verifies and adds a instruction to the end of the collection that pushes a 64-bit integer constant.

public CilInstruction Add(CilOpCode code, long constant)

Parameters

code CilOpCode

The opcode.

constant long

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a 64-bit integer constant.

Add(CilOpCode, float)

Verifies and adds a instruction to the end of the collection that references a float32 constant.

public CilInstruction Add(CilOpCode code, float constant)

Parameters

code CilOpCode

The opcode.

constant float

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a float32 constant.

Add(CilOpCode, string)

Verifies and adds a instruction to the end of the collection that pushes a string constant.

public CilInstruction Add(CilOpCode code, string constant)

Parameters

code CilOpCode

The opcode.

constant string

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a string constant.

ArgumentNullException

Occurs when constant is null.

AddRange(IEnumerable<CilInstruction>)

Adds a collection of CIL instructions to the end of the list.

public void AddRange(IEnumerable<CilInstruction> items)

Parameters

items IEnumerable<CilInstruction>

The instructions to add.

CalculateOffsets()

Calculates the offsets of each instruction in the list.

public void CalculateOffsets()

Clear()

public void Clear()

Contains(CilInstruction)

public bool Contains(CilInstruction item)

Parameters

item CilInstruction

Returns

bool

CopyTo(CilInstruction[], int)

public void CopyTo(CilInstruction[] array, int arrayIndex)

Parameters

array CilInstruction[]

arrayIndex int

ExpandMacros()

Simplifies the CIL instructions by transforming macro instructions to their expanded form.

public void ExpandMacros()

Remarks

This method reverses any optimizations done by OptimizeMacros().

GetEnumerator()

Returns an enumerator that enumerates through the instructions sequentially.

public CilInstructionCollection.Enumerator GetEnumerator()

Returns

CilInstructionCollection.Enumerator

The enumerator.

GetLabel(int)

Gets a label at the provided offset.

public ICilLabel GetLabel(int offset)

Parameters

offset int

The offset.

Returns

ICilLabel

The label.

Remarks

If the provided offset falls outside of the CIL code stream, EndLabel is returned instead.

IndexOf(CilInstruction)

public int IndexOf(CilInstruction item)

Parameters

item CilInstruction

Returns

int

Insert(int, CilInstruction)

public void Insert(int index, CilInstruction item)

Parameters

index int

item CilInstruction

Insert(int, CilOpCode)

Verifies and inserts an instruction into the collection.

public CilInstruction Insert(int index, CilOpCode code)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The code.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation requires an operand.

Insert(int, CilOpCode, CilLocalVariable)

Verifies and inserts a instruction into the collection that references a local variable.

public CilInstruction Insert(int index, CilOpCode code, CilLocalVariable variable)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

variable CilLocalVariable

The referenced variable.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a variable.

ArgumentNullException

Occurs when variable is null.

Insert(int, CilOpCode, Parameter)

Verifies and inserts a instruction into the collection that references a parameter.

public CilInstruction Insert(int index, CilOpCode code, Parameter parameter)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

parameter Parameter

The referenced parameter.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a parameter.

ArgumentNullException

Occurs when parameter is null.

Insert(int, CilOpCode, IFieldDescriptor)

Verifies and inserts an instruction into the collection that references a field.

public CilInstruction Insert(int index, CilOpCode code, IFieldDescriptor field)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The field opcode.

field IFieldDescriptor

The field referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a field opcode.

ArgumentNullException

Occurs when field is null.

Insert(int, CilOpCode, IMetadataMember)

Verifies and inserts an instruction into the collection that references a metadata member.

public CilInstruction Insert(int index, CilOpCode code, IMetadataMember member)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The method opcode.

member IMetadataMember

The member referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a member opcode.

ArgumentNullException

Occurs when member is null.

Insert(int, CilOpCode, IMethodDescriptor)

Verifies and inserts an instruction into the collection that references a method.

public CilInstruction Insert(int index, CilOpCode code, IMethodDescriptor method)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The method opcode.

method IMethodDescriptor

The method referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a method opcode.

ArgumentNullException

Occurs when method is null.

Insert(int, CilOpCode, ITypeDefOrRef)

Verifies and inserts an instruction into the collection that references a type.

public CilInstruction Insert(int index, CilOpCode code, ITypeDefOrRef type)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The type opcode.

type ITypeDefOrRef

The type referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a type opcode.

ArgumentNullException

Occurs when type is null.

Insert(int, CilOpCode, MemberReference)

Verifies and inserts an instruction into the collection that references a member.

public CilInstruction Insert(int index, CilOpCode code, MemberReference member)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The member opcode.

member MemberReference

The member referenced by the instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation does not match with the provided member reference.

ArgumentNullException

Occurs when member is null.

Insert(int, CilOpCode, StandAloneSignature)

Verifies and inserts a instruction into the collection that references a standalone signature referencing a method signature in the blob stream.

public CilInstruction Insert(int index, CilOpCode code, StandAloneSignature signature)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

signature StandAloneSignature

The referenced signature.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a standalone signature.

Insert(int, CilOpCode, ICilLabel)

Verifies and inserts a branch instruction into the collection.

public CilInstruction Insert(int index, CilOpCode code, ICilLabel label)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The branch opcode.

label ICilLabel

The label referenced by the branch instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a branch opcode.

ArgumentNullException

Occurs when label is null.

Insert(int, CilOpCode, params ICilLabel[])

Verifies and inserts a switch instruction into the collection.

public CilInstruction Insert(int index, CilOpCode code, params ICilLabel[] labels)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The switch opcode.

labels ICilLabel[]

The labels referenced by the switch instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a branch opcode.

ArgumentNullException

Occurs when labels is null.

Insert(int, CilOpCode, MetadataToken)

Verifies and inserts a instruction into the collection that references a metadata member by its token.

public CilInstruction Insert(int index, CilOpCode code, MetadataToken token)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

token MetadataToken

The token of the referenced member.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a metadata member.

ArgumentOutOfRangeException

Occurs when the provided token is not valid in a CIL stream.

Insert(int, CilOpCode, IEnumerable<ICilLabel>)

Verifies and inserts a switch instruction into the collection.

public CilInstruction Insert(int index, CilOpCode code, IEnumerable<ICilLabel> labels)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The switch opcode.

labels IEnumerable<ICilLabel>

The labels referenced by the switch instruction.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not a branch opcode.

ArgumentNullException

Occurs when labels is null.

Insert(int, CilOpCode, double)

Verifies and inserts a instruction into the collection that references a float64 constant.

public CilInstruction Insert(int index, CilOpCode code, double constant)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

constant double

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a float64 constant.

Insert(int, CilOpCode, int)

Verifies and inserts a instruction into the collection that pushes an integer constant.

public CilInstruction Insert(int index, CilOpCode code, int constant)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

constant int

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing an integer constant.

Insert(int, CilOpCode, long)

Verifies and inserts a instruction into the collection that pushes a 64-bit integer constant.

public CilInstruction Insert(int index, CilOpCode code, long constant)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

constant long

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a 64-bit integer constant.

Insert(int, CilOpCode, float)

Verifies and inserts a instruction into the collection that references a float32 constant.

public CilInstruction Insert(int index, CilOpCode code, float constant)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

constant float

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a float32 constant.

Insert(int, CilOpCode, string)

Verifies and inserts a instruction into the collection that pushes a string constant.

public CilInstruction Insert(int index, CilOpCode code, string constant)

Parameters

index int

The zero-based index at which the instruction should be inserted at.

code CilOpCode

The opcode.

constant string

The constant to push.

Returns

CilInstruction

The created instruction.

Exceptions

InvalidCilInstructionException

Occurs when the provided operation is not an opcode referencing a string constant.

ArgumentNullException

Occurs when constant is null.

InsertRange(int, IEnumerable<CilInstruction>)

Inserts a collection of CIL instructions at the provided index.

public void InsertRange(int index, IEnumerable<CilInstruction> items)

Parameters

index int

The index to insert the instructions into.

items IEnumerable<CilInstruction>

The instructions to insert.

OptimizeMacros()

Optimizes all instructions to use the least amount of bytes required to encode all operations.

public void OptimizeMacros()

Remarks

This method reverses any effects introduced by ExpandMacros().

Remove(CilInstruction)

public bool Remove(CilInstruction item)

Parameters

item CilInstruction

Returns

bool

RemoveAt(int)

public void RemoveAt(int index)

Parameters

index int

RemoveAt(int, IEnumerable<int>)

Removes a set of CIL instructions based on a list of indices that are relative to a starting index.

public void RemoveAt(int baseIndex, IEnumerable<int> relativeIndices)

Parameters

baseIndex int

The base index.

relativeIndices IEnumerable<int>

The indices relative to baseIndex to remove.

Exceptions

ArgumentOutOfRangeException

Occurs when any relative index in relativeIndices results in an index that is out of bounds of the instruction collection.

RemoveAt(int, params int[])

Removes a set of CIL instructions based on a list of indices that are relative to a starting index.

public void RemoveAt(int baseIndex, params int[] relativeIndices)

Parameters

baseIndex int

The base index.

relativeIndices int[]

The indices relative to baseIndex to remove.

Exceptions

ArgumentOutOfRangeException

Occurs when any relative index in relativeIndices results in an index that is out of bounds of the instruction collection.

RemoveRange(IEnumerable<CilInstruction>)

Removes a set of CIL instructions from the collection.

public void RemoveRange(IEnumerable<CilInstruction> items)

Parameters

items IEnumerable<CilInstruction>

The instructions to remove.

RemoveRange(int, int)

Removes a range of CIL instructions from the collection.

public void RemoveRange(int index, int count)

Parameters

index int

The starting index.

count int

The number of instructions to remove.