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.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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

Gets the number of elements contained in the ICollection<T>.

public int Count { get; }

Property Value

int

The number of elements contained in the ICollection<T>.

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

Gets a value indicating whether the ICollection<T> is read-only.

public bool IsReadOnly { get; }

Property Value

bool

true if the ICollection<T> is read-only; otherwise, false.

this[int]

Gets or sets the element at the specified index.

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

Parameters

index int

The zero-based index of the element to get or set.

Property Value

CilInstruction

The element at the specified index.

Exceptions

ArgumentOutOfRangeException

index is not a valid index in the IList<T>.

NotSupportedException

The property is set and the IList<T> is read-only.

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)

Adds an item to the ICollection<T>.

public void Add(CilInstruction item)

Parameters

item CilInstruction

The object to add to the ICollection<T>.

Exceptions

NotSupportedException

The ICollection<T> is read-only.

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()

Removes all items from the ICollection<T>.

public void Clear()

Exceptions

NotSupportedException

The ICollection<T> is read-only.

Contains(CilInstruction)

Determines whether the ICollection<T> contains a specific value.

public bool Contains(CilInstruction item)

Parameters

item CilInstruction

The object to locate in the ICollection<T>.

Returns

bool

true if item is found in the ICollection<T>; otherwise, false.

CopyTo(CilInstruction[], int)

Copies the elements of the ICollection<T> to an Array, starting at a particular Array index.

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

Parameters

array CilInstruction[]

The one-dimensional Array that is the destination of the elements copied from ICollection<T>. The Array must have zero-based indexing.

arrayIndex int

The zero-based index in array at which copying begins.

Exceptions

ArgumentNullException

array is null.

ArgumentOutOfRangeException

arrayIndex is less than 0.

ArgumentException

The number of elements in the source ICollection<T> is greater than the available space from arrayIndex to the end of the destination array.

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)

Determines the index of a specific item in the IList<T>.

public int IndexOf(CilInstruction item)

Parameters

item CilInstruction

The object to locate in the IList<T>.

Returns

int

The index of item if found in the list; otherwise, -1.

Insert(int, CilInstruction)

Inserts an item to the IList<T> at the specified index.

public void Insert(int index, CilInstruction item)

Parameters

index int

The zero-based index at which item should be inserted.

item CilInstruction

The object to insert into the IList<T>.

Exceptions

ArgumentOutOfRangeException

index is not a valid index in the IList<T>.

NotSupportedException

The IList<T> is read-only.

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)

Removes the first occurrence of a specific object from the ICollection<T>.

public bool Remove(CilInstruction item)

Parameters

item CilInstruction

The object to remove from the ICollection<T>.

Returns

bool

true if item was successfully removed from the ICollection<T>; otherwise, false. This method also returns false if item is not found in the original ICollection<T>.

Exceptions

NotSupportedException

The ICollection<T> is read-only.

RemoveAt(int)

Removes the IList<T> item at the specified index.

public void RemoveAt(int index)

Parameters

index int

The zero-based index of the item to remove.

Exceptions

ArgumentOutOfRangeException

index is not a valid index in the IList<T>.

NotSupportedException

The IList<T> is read-only.

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.