MSIL Assembler (Ilasm.exe)

The MSIL Assembler generates a portable executable (PE) file from MSIL assembly language. 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...]
Argument Description
filename The name of the .il source file. This file consists of metadata declaration directives and symbolic MSIL instructions. Multiple source file arguments can be supplied to produce a single PE file with Ilasm.exe.
Option Description
/alignment=integer Sets FileAlignment to the value specified by integer in the NT Optional header. If the .alignment IL directive is specified in the file, this option overrides it.
/base=integer Sets ImageBase to the value specified by integer in the NT Optional header. If the .imagebase IL directive is specified in the file, this option overrides it.
/clock Measures and reports the following compilation times in milliseconds for the specified .il source file:
Total Run
The total time spent performing all the specific operations that follow.
Startup
Loading and opening the file.

Parsing

Emitting MD
Emitting metadata.
Ref to Def Resolution
Resolving references to definitions in the file.

Fixup and Linking

CEE File Generation
Generating the file image in memory.
PE File Writing
Writing the image to a PE file.
/debug Includes debug information (local variable and argument names, and line numbers).
/dll Produces a .dll file as output.
/exe Produces an executable file as output. This is the default.
/flags=integer Sets ImageFlags to the value specified by integer in the common language runtime header. If the .corflags IL directive is specified in the file, this option overrides it. See CorHdr.h , COMIMAGE_FLAGS for a list of valid values for integer.
/key:keyFile Compiles filename with a strong signature using the private key contained in keyFile.
/key:@keySource Compiles filename with a strong signature using the private key produced at keySource.
/listing Produces a listing file on the standard output. If you omit this option, no listing file is produced.
/nologo Suppresses the Microsoft startup banner display.
/output:file.ext Specifies the output file name and extension. By default, the output file name is the same as the name of the first source file. The default extension is .exe. If you specify the /dll option, the default extension is .dll.
Note   Specifying /output:myfile.dll does not set the /dll option. If you do not specify /dll, the result will be an executable file named myfile.dll.
/quiet Specifies quiet mode; does not report assembly progress.
/resource:file.res Includes the specified resource file in *.res format in the resulting .exe or .dll file. Only one .res file can be specified with the /resource option.
/subsystem=integer Sets subsystem to the value specified by integer in the NT Optional header. If the .subsystem IL directive is specified in the file, this command overrides it. See winnt.h, IMAGE_SUBSYSTEM for a list of valid values for integer.
/? Displays command syntax and options for the tool.

Note   All options for Ilasm.exe are case-insensitive and recognized by the first three letters. For example, /lis is equivalent to /listing and **/res:**myresfile.res is equivalent to **/resource:**myresfile.res. Options that specify arguments accept either a colon (:) or an equal sign (=) as the separator between the option and the argument. For example, **/output:**file.ext is equivalent to **/output=**file.ext.

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 .NET, 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.

Note   Currently, you cannot use this technique with PE files that contain embedded native code (for example, PE files produced by Visual C++ .NET).

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.

Note   Ildasm.exe only operates on files on disk. It does not operate on files installed in the global assembly cache.

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

See Also

.NET Framework Tools | MSIL Disassembler(Ildasm.exe) | Microsoft Intermediate Language