NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

NGWS Runtime IL Assembler (ilasm.exe)

IL is the intermediate language that is converted to machine language by the NGWS runtime's JIT compilers. Tools that generate IL can benefit from the common infrastructure provided by the runtime, the IL support for early and late binding, and the fact that code compiled to IL will run on any platform supported by the runtime. The ease with which IL can be generated is advantageous in RAD (rapid application development) environments, where fast compilation and easy debugging are of primary importance. The runtime manages source code that is compiled to IL during execution so that it benefits from features such as cross-language inheritance, code access security, garbage-collection, and simplified COM programming.

To assist tools vendors with the task of designing and implementing IL generators, the runtime provides the IL Assembler, ilasm. This tool takes IL as input and generates a portable executable (PE) file containing the IL and the required metadata. The resulting executable can be run to determine whether the IL performs as expected. The IL Assembler allows tools developers to concentrate on IL generation without being concerned with emitting IL in the PE file format. This tool is intended primarily for testing the performance of small sequences of IL and to test IL generation strategies.

Although the IL Assembler is helpful in the early stages of generating IL, it has some limitations: it does not emit all possible runtime PE file features, and it cannot produce a PE file that can be statically linked with other files (an .obj file). Therefore, the IL Assembler is not intended to provide a long-term solution. Compilers and other tools that generate IL must eventually emit the PE file format expected by the runtime.

There is a companion tool, ildasm, that takes a PE file containing IL code and creates a text file suitable as input to the IL Assembler. This ability to round trip code can be useful, for example, when compiling code in a programming language that doesn't support all of the runtime metadata attributes. The code can be compiled, then the output run through ildasm, and the resulting IL text file can be hand edited to add the missing attributes. This can then be run through the IL Assembler to produce a final, runnable file.

In order to make this round tripping possible, the assembler does not perform some simple optimizations that are provided by other assemblers: it does not deduce whether to use short or long forms of instructions. For example, the tool does not try to determine if it could substitute a short encoding for the long one you may have written in your IL sources; if you want the short encoding, you must explicitly write that form.

The assembler does, however, check for out-of-range conditions where this is possible.

Note At the present time, PE files produced by Visual C++ can't be round-tripped using ilasm.

Syntax

ilasm [options] filename [options]

In the following list, boldface means the argument is assumed by default.

Option Description
/DEBUG Includes debug info (local variable and argument names, line numbers).
/DLL Produces a .dll file rather than an .exe file as output.
/EXE Produces an .exe file rather than a .dll file as output.
filename Name of the .il file. The file consists of IL surrounded by assembler directives at the class, method, and field level.
/LISTING Produces a listing file on the standard output.
/NOLISTING Doesn't produce a listing file.
/OUTPUT=<file.ext> Set the output file name and extension. By default, the output file name is the same as input (source) file name, and extension is .exe or .dll (if /DLL option is specified).

The file extension must be specified (unless it is intentionally omitted).

Warning: specifying /OUTPUT=myfile.dll will not set the /DLL option; if /DLL option is not specified, the result will be an .exe file named myfile.dll.

/OWNER=<OwnersName> Sets the owner’s name or password (no spaces allowed), so future disassembly with ildasm tool would be possible only if this name is provided. If <OwnersName> is omitted, the ildasm tool will not disassemble the generated .exe or .dll file.
/QUIET Don't report assembly progress.
/RESOURCE=<file.res> Include the resource file in *.res format (no more than one) into resulting .exe or .dll file.

All ILASM and ILDASM options are recognized by first three letters, so /NOL equals /NOLISTING, /RES=myresfile.res equals /RESOURCE=myresfile.res, etc. The options are case-insensitive.

See Also

NGWS Runtime IL Disassembler