InlineIL.Fody

This is an add-in for Fody which lets you inject arbitrary IL into your assembly at compile time.

Installation
Usage
Configuration
Examples

Installation

Install the NuGet packages Fody and InlineIL.Fody. Installing Fody explicitly is needed to enable weaving.
```
PM> Install-Package Fody
PM> Install-Package InlineIL.Fody
```
Add the PrivateAssets="all" metadata attribute to the <PackageReference /> items of Fody and InlineIL.Fody in your project file, so they won't be listed as dependencies.
If you already have a FodyWeavers.xml file in the root directory of your project, add the <InlineIL /> tag there. This file will be created on the first build if it doesn't exist:
```
<?xml version="1.0" encoding="utf-8" ?>
<Weavers>
  <InlineIL />
</Weavers>
```

See Fody usage for general guidelines, and Fody Configuration for additional options.

Usage

Call static methods of the InlineIL.IL.Emit class to emit IL instructions. That's it. 😉

A few more things which are good to know:

The InlineIL.IL class exposes methods for handling labels and local variables, and some utilities (see below).
System.Type is implicitly convertible to InlineIL.TypeRef: when you see a TypeRef parameter, you can use the typeof keyword in most cases.
You can add the using static InlineIL.IL.Emit; directive to get rid of the IL.Emit prefix.
You don't have to emit instructions in their short form, they will be shortened automatically (e.g. ldarg.0 will be emitted instead of ldarg 0).
Most types used as operands declare instance methods which change their meaning and can be chained, for instance: new TypeRef(...).MakeArrayType().MakeByRefType().
You can combine InlineIL instructions with existing C# code: a given method doesn't have to be entirely written in IL. After weaving, the reference to the InlineIL assembly is removed from your project.

Methods

IL.Emit.*
Every method call on the IL.Emit class will be replaced by the IL instruction it represents.
Note that all arguments to these methods need to be constructed in place (i.e. the instruction needs to be representable in IL).
IL.DeclareLocals
Declares local variables. Supports changing the init flag and pinned variables. Local variables can be referenced by name or by index.
IL.MarkLabel
Marks a label at a given position in the code.
IL.Push
Pushes the provided argument onto the evaluation stack. Does not require a constatnt argument, any expression will work.
IL.Pop
Pops a value from the evaluation stack into a local variable or static field.
IL.Unreachable
Marks an unreachable code region, for instance just after a ret instruction. Necessary when the compiler's control flow analysis requires a code statement.
Usage: throw IL.Unreachable();
IL.Return, IL.ReturnRef, IL.ReturnPointer
Helper methods to return the value from the top of the evaluation stack.
Example usage: return IL.Return<int>();

Types

TypeRef
A class which represents a type. Note that System.Type is implicitly convertible to TypeRef, so you can directly write typeof(int) for instance where a TypeRef parameter is expected.
MethodRef
A method reference. Exposes a simple constructor for methods without overloads, and some more detailed ones for overload disambiguation. Additional static factory methods for referencing underlying methods of properties and events are provided for convenience.
Use TypeRef.TypeGenericParameters[N] and TypeRef.MethodGenericParameters[N] to represent the generic parameter of index N in MethodRef calls which involve overload resolution.
FieldRef
A field reference.
StandAloneMethodSig
A method signature for use as an operand to the calli instruction.
LocalVar
Declares a local variable (with an optional name), for use with IL.DeclareLocals. Implicitly convertible from System.Type if you don't want to use named locals or pinning.

Configuration

The <InlineIL /> element in FodyWeavers.xml accepts the following attribute:

SequencePoints="True|False|Debug|Release", default value: Debug
Defines if sequence points should be generated for each emitted IL instruction. The default Debug value improves the debugging experience in Debug builds without impacting the JIT codegen in Release builds.

Examples

A reimplementation of the System.Runtime.CompilerServices.Unsafe class using InlineIL is provided as an example (compare to the original IL code).
Unit tests can also serve as examples of API usage. See verifiable and unverifiable test cases.

Simple example:

public static void ZeroInit<T>(ref T value)
    where T : struct
{
    Ldarg(nameof(value));
    Ldc_I4_0();
    Sizeof(typeof(T));
    Unaligned(1);
    Initblk();
}

What gets compiled:

.method public hidebysig static 
  void ZeroInit<valuetype .ctor ([mscorlib]System.ValueType) T> (
    !!T& 'value'
  ) cil managed 
{
  .maxstack 8

  IL_0000: ldarg.0
  IL_0001: ldc.i4.0
  IL_0002: sizeof !!T
  IL_0008: unaligned. 1
  IL_000b: initblk
  IL_000d: ret
}

two06 / InlineIL.Fody