The .assembly directive defines the simple name of the assembly. The simple name does not include the extension. Assembly probing will discover the correct extension. Adding the extension will cause normal probing to fail. A binding exception will occur when the assembly is referenced.

Here is the syntax of the .assembly directive:

.assembly name { block }

The assembly block contains additional directives that further describe the assembly. These directives are optional. You need to provide only enough directives to identify the assembly uniquely. Here is an assembly block with additional details:

.assembly Hello {
    .ver 1:0:0:0
    .locale "en.US"
}

These are some of the directives available in the assembly block:

The .assembly extern directive references an external assembly. The public types and methods of the referenced assembly are available to the current assembly.

Here is the syntax of the .assembly extern directive:

.assembly extern name as aliasname {block}

The as clause is optional. Use this clause to reference an assembly with the same name that has a different version, public key, or culture.

Add the .ver, .publickey, .locale, and .custom directives to the assembly extern block to refine the identification of that assembly.

Because of the importance of mscorlib.dll, the ILASM compiler automatically includes an external reference to that library. Therefore, adding an .assembly extern mscorlib directive is purely informative.

The .file directive adds a file to the manifest of the assembly. This is useful for associating documents, such as a readme file, with an assembly.

Here is the syntax of the .file directive:

.file nometadata filename .hash = (bytes) .entrypoint

The file name is the sole required element of the declaration. Nometadata is the primary option and stipulates that the file is unmanaged. Here is an example:

.file nometadata documentation.txt

The .subsystem directive indicates the subsystem used by the application, such as the graphical user interface (GUI) or console subsystem. This is distinct from the target type of the application, which is an executable, library, module, or other type. The ILASM compiler inserts this directive based on options specified when the application is compiled. You also can add this directive explicitly.

Here is the syntax of the .subsystem directive:

.subsystem number

Number is a 32-bit integer in which 2 is a GUI application and 3 is a console application.

The .corflags directive sets the runtime flag in the Common Language Infrastructure (CLI) header. This defaults to 1, which stipulates an IL-only assembly. The corflags tool, introduced in .NET 2.0, allows the configuration of this flag.

Here is the syntax of the .corflags directive:

.corflags flag

where flag is a 32-bit integer.

The .stackreserve directive sets the stack size. The default size is 0x00100000. The following code calls MethodA recursively. Without the .stackreserve directive, which defaults to 0x00100000, the MethodA method is called recursively more than 110,000 times before exhausting the stack. If you set the stack size to 0x0001000 using the .stackreserve directive, MethodA is called only about 21,000 times before quitting. Although the results may vary on your actual computer, the relative values are consistent:

.assembly recursive {}
.imagebase 0x00800000
.stackreserve 0x00001000

.namespace Donis.CSharpBook {
    .class Starter {
        .method static public void Main() il managed {
            .entrypoint
            ldc.i4.0
            call void Donis.CSharpBook.Starter::MethodA(int32)
            ret
        }

        .method static public void MethodA(int32) il managed {
            ldarg.0
            ldc.i4.1
            add
            dup
            call void [mscorlib] System.Console::WriteLine(int32)
            call void Donis.CSharpBook.Starter::MethodA(int32)
            ret
        }
    }
}

The .imagebase directive sets the base address where the application is loaded. The default is 0x00400000. The load address of the application image and the stack size are confirmable using the dumpbin tool. For example, see the following code:

dumpbin /headers recursive.exe >recursive.txt

The .class directive defines a new reference, value, or interface type.

Here is the syntax of the header portion of the .class directive:

attributes classname extends basetype implements interfaces

There are a variety of attributes. Here is a short list of the most common of these:

The extends option is used if the type inherits from another type. .NET supports only single class inheritance. The extends option is optional. If that option is not present, the type inherits implicitly from System.Object.

The implements option lists the interfaces implemented by the type. The implements clause is optional, and there are no default interfaces. The list of interfaces is comma-delimited.

In the members block, members are declared with the appropriate directive: .method, .field, .property, and so on.

The .custom directive adds a custom attribute to the type.

The .method directive defines a method. C# does not support global methods. Therefore, in MSIL that is derived from C# source code, the .method directive always is included within a type.

Here is the syntax of the .method directive:

.method attributes callingconv return methodname arguments implattributes {methodbody }

The method attributes are varied, including the accessibility attributes: public, private, family, and others. The default is private. Static methods have the static attribute, whereas instance methods have the instance attribute. The default is an instance method.

Here are additional attributes:

The calling convention pertains mostly to native code, in which a variety of calling conventions are supported: fastcall, cdecl, and others.

The implementation attributes include (but are not limited to) the following:

Here is the declaration of a C# method:

virtual public int MethodA(int param1, int param2)

Here is the MSIL code for that same method:

.method public hidebysig newslot virtual instance int32 MethodA(
    int32 param1, int32 param2) cil managed

The .field directive defines a new field, which is state information for a class. Instance fields are data for an object. Static fields are data for a class.

The syntax of the .field directive is as follows:

.field attributes type fieldname fieldinit at datalabel

The accessibility attributes are the same as described with methods. Static fields must be assigned the static attribute. The default is an instance field. The initonly attribute defines a read-only field.

Here is a field defined in a C# class:

private readonly int fielda = 10;

Here is the same field translated to MSIL code. The compiler also adds a no-argument constructor, where fielda is initialized to 10 (not shown here).

.field private initonly int32 fielda

The .property directive adds a property member to a class. It also declares the get and set methods for the property.

Here is the syntax of the .property directive:

.property attributes return propertyname parameters default { propertyblock }

The attributes of a property are similar to those of a class and method. Return is the return type of the property. Propertyname and parameters are the signature of the property. The default option sets the default value of the property.

Within propertyblock, the .get directive declares the signature of the get method, whereas the .set directive declares the set method. The propertybody block includes only the method declarations. The get and set methods actually are implemented at the class level, not within the property.

Here is a property defined and implemented in a C# application:

public int propa {
    get {
        return 0;
    }
}

Here is the declaration of the property in the MSIL code (the implementation of the get.propa method is not shown):

.property instance int32 propa()
{
    .get instance int32 Donis.CSharpBook.Starter::get_propa()
}

The .event directive adds an event in a class.

Here is the syntax of the .event directive:

.event classref eventname { eventbody }

Classref is the underlying type of the event, such as EventHandler.

The eventbody block encapsulates the .addon and .removeon directives. The .addon directive declares the method used to add subscribers. The .removeon directive declares the method for removing subscribers. The add and remove methods are implemented in the class and not within the event.

Here is the C# code that declares an event:

public event EventHandler EventA;

Here is the MSIL code for the event:

.event [mscorlib]System.EventHandler EventA {
    .addon instance void Donis.CSharpBook.Starter::add_EventA(
        class [mscorlib]System.EventHandler)
    .removeon instance void Donis.CSharpBook.Starter::remove_EventA(
        class [mscorlib]System.EventHandler)
}

The .locals directive declares local variables that are available by name or index. Local variables form a zero-based array.

Here is the syntax of the .locals directive:

.locals1 ([index]local1, [index] local2, [index] localn)

.locals2 init ([index]local1, [index] local2, [index] localn)

The .locals¹ directive defines one or more local variables. Explicit indexes can be set for each local variable. By default, the local variables are indexed sequentially starting at zero.

The .locals² directive adds the init keyword, which requests that local variables be initialized to either null or zero . The init keyword is required for the assembly to pass code verification. Therefore, the C# compiler emits only the .locals² directive.

Local variables do not have to be declared at the beginning of a method.

The .maxstack directive sets the number of slots available on the evaluation stack, which is the number of items that can exist on the evaluation stack simultaneously. Without this directive, the default is eight slots.

Here is the syntax of the .maxstack directive:

.maxstack slots

The .entrypoint directive designates a method as the entry point method of the application. This directive can appear anywhere in the method, but best practice is to put the .entrypoint directive at the start of the method.

In C#, the entry point method is Main. In MSIL, any static method can be given this status.

Some MSIL instructions have a normal and a short-form syntax. The short form of the instruction has an .s suffix. The short form of the ldloc instruction is ldloc.s. The short form of the br instruction is br.s. Normal instructions have 4-byte operands, and short-form instructions are limited to 1-byte operands.

When used injudiciously, the short-form syntax can cause unexpected results. Consider the following example:

.assembly extern mscorlib {}
.assembly application {}

.namespace Donis.CSharpBook {

    .class Starter {
        .method static public void Main() il managed {
            .entrypoint
            ldc.i4.s 50000
            call void [mscorlib] System.Console::WriteLine(int32)
            ret
        }
    }
}

In the preceding application, a constant of 50000 is placed on the evaluation stack. However, the ldc instruction is in the short form. You cannot fit 50000 into a single byte, so the constant overflows the byte. For this reason, the application incorrectly displays 80.

There are categories of MSIL instructions. The next section reviews these categories, such as branch, arithmetic, call, and array groups of instructions. Because of the prevalence of the evaluation stack, load and store instructions are the most frequently used of all MSIL instructions. That is a good place to start.