MSIL Assembler (Ilasm.exe)

The MSIL Assembler generates a portable executable (PE) file from Microsoft intermediate language (MSIL). (For more information on MSIL, see Compiling to MSIL). You can run the resulting executable, which contains MSIL and the required metadata, to determine whether the MSIL performs as expected.

ilasm [options] filename [[options]filename...]

Parameters

Remarks

The MSIL Assembler helps tool vendors design and implement MSIL generators. Using Ilasm.exe, tool and compiler developers can concentrate on MSIL and metadata generation without being concerned with emitting MSIL in the PE file format.

Similar to other compilers that target the runtime, such as C# and Visual Basic, Ilasm.exe does not produce intermediate object files and does not require a linking stage to form a PE file.

The MSIL Assembler can express all the existing metadata and MSIL features of the programming languages that target the runtime. This allows managed code written in any of these programming languages to be adequately expressed in MSIL Assembler and compiled with Ilasm.exe.

You can use Ilasm.exe in conjunction with its companion tool, Ildasm.exe. Ildasm.exe takes a PE file that contains MSIL code and creates a text file suitable as input to Ilasm.exe. This is useful, for example, when compiling code in a programming language that does not support all the runtime metadata attributes. After compiling the code and running the output through Ildasm.exe, the resulting MSIL text file can be hand-edited to add the missing attributes. You can then run this text file through the Ilasm.exe to produce a final executable file.

You can also use this technique to produce a single PE file from several PE files originally generated by different compilers.

To make this combined use of Ildasm.exe and Ilasm.exe as accurate as possible, the assembler does not perform some simple optimizations — it does not deduce whether to use short or long forms of instructions. For example, the tool does not try to determine whether it could substitute a short encoding for a long one you might have written in your MSIL sources (or that might be emitted by another compiler). If you want the short encoding, you must explicitly write that form. However, the assembler does check for out-of-range conditions where this is possible.

For more information about the grammar of MSIL, see the asmparse.grammar file in the Windows Software Development Kit (SDK).

Examples

The following command assembles the MSIL file myTestFile.il and produces the executable myTestFile.exe.

ilasm myTestFile

The following command assembles the MSIL file myTestFile.il and produces the .dll file myTestFile.dll.

ilasm myTestFile /dll 

The following command assembles the MSIL file myTestFile.il and produces the .dll file myNewTestFile.dll.

ilasm myTestFile /dll /output:myNewTestFile.dll

The following code example shows an extremely simple application that displays "Hello World!" to the console. You can compile this code and then use the Ildasm.exe tool to generate an MSIL file.

using System;
public class Hello
{
    public static void Main(String[] args)
    {
        Console.WriteLine("Hello World!");
    }
}

The following MSIL code example corresponds to the previous C# code example. You can compile this code into an assembly using the MSIL Assembler (Ilasm.exe) tool. Both MSIL and C# code examples display "Hello World!" to the console.

// Metadata version: v2.0.50215
.assembly extern mscorlib
{
  .publickeytoken = (B7 7A 5C 56 19 34 E0 89 )                         // .z\V.4..
  .ver 2:0:0:0
}
.assembly sample
{
  .custom instance void [mscorlib]System.Runtime.CompilerServices.CompilationRelaxationsAttribute::.ctor(int32) = ( 01 00 08 00 00 00 00 00 ) 
  .hash algorithm 0x00008004
  .ver 0:0:0:0
}
.module sample.exe
// MVID: {A224F460-A049-4A03-9E71-80A36DBBBCD3}
.imagebase 0x00400000
.file alignment 0x00000200
.stackreserve 0x00100000
.subsystem 0x0003       // WINDOWS_CUI
.corflags 0x00000001    //  ILONLY
// Image base: 0x02F20000


// =============== CLASS MEMBERS DECLARATION ===================

.class public auto ansi beforefieldinit Hello
       extends [mscorlib]System.Object
{
  .method public hidebysig static void  Main(string[] args) cil managed
  {
    .entrypoint
    // Code size       13 (0xd)
    .maxstack  8
    IL_0000:  nop
    IL_0001:  ldstr      "Hello World!"
    IL_0006:  call       void [mscorlib]System.Console::WriteLine(string)
    IL_000b:  nop
    IL_000c:  ret
  } // end of method Hello::Main

  .method public hidebysig specialname rtspecialname 
          instance void  .ctor() cil managed
  {
    // Code size       7 (0x7)
    .maxstack  8
    IL_0000:  ldarg.0
    IL_0001:  call       instance void [mscorlib]System.Object::.ctor()
    IL_0006:  ret
  } // end of method Hello::.ctor

} // end of class Hello

See Also

Concepts

Compiling to MSIL

Reference

.NET Framework Tools

MSIL Disassembler (Ildasm.exe)

SDK Command Prompt