IL Disassembler | Inside Microsoft .NET IL Assembler

IL Disassembler

The IL Disassembler tool, Ildasm.exe, is distributed with the .NET Framework SDK and is one of the most popular tools among developers working on .NET-based programs. Virtually every book dedicated to .NET themes at least mentions ILDASM and briefly describes its features.

ILDASM is a dual-mode application—that is, it can run either as a console or as a GUI application. Two ILDASM command-line options—/OUT:<file_name> and /TEXT—set the disassembler mode. If either /TEXT or /OUT:CON is specified, ILDASM outputs the disassembly text to the console window from which it was started. If /OUT:<file_name> is specified, ILDASM dumps the disassembly text into the specified file. If neither /TEXT nor /OUT is specified, ILDASM switches to graphical mode.

The graphical user interface of ILDASM is rather modest and strictly functional. The disassembled module is represented as a tree. The module itself is shown as the root, namespaces and classes as tree nodes, and members—methods, fields, events, and properties—as tree leaves. Double-clicking a tree leaf displays a disassembly window containing the ILAsm source text of the corresponding item of the module, as shown in Figure 16-1.

Figure 16-1 The IL Disassembler in graphical mode.

The tree leaf MANIFEST corresponds to all module-level information, including manifest metadata, module metadata, and v-table fixups.

Each tree node representing a type has special leaves providing information about the type: a class leaf, an extends leaf (if the type is derived from another type), and one implements leaf for each interface the type implements. Double-clicking a class leaf displays a disassembly window containing full class information except for the disassembly of the class members. Double-clicking an extends leaf or an implements leaf moves the cursor in the tree view to the respective class or interface if it is defined in the current module.

The disassembler provides numerous viewing options that allow you to control the disassembly text presentation. In graphical mode, these options are listed on the View menu, as shown in Figure 16-2.

Figure 16-2 Disassembler viewing options.

The module opened in ILDASM’s graphical mode can be dumped to a file but not to a console window. To dump the module to a file, choose Dump from the File menu, set the dump options as shown in Figure 16-3, and click OK. In the Save As dialog box displayed, specify a directory and the name of an output file. To dump a text representation of the fully expanded tree view to a specified file, choose DumpTree from the File menu.

For reasons I won’t discuss here, the disassembler does not offer all possible viewing options by default. To access all the options, you must use the /ADVANCED (or /ADV, because ILDASM options are recognized by their first three characters) command-line option. I strongly recommend that you make it a habit to invoke the disassembler as ildasm /adv < other options > to avoid the frustration of being unable to access the option you need and being forced to close and restart ILDASM. And, yes, I know it’s inconvenient.

Certain options are available only in advanced mode. Among them, the group of /METAINFO options, which provide various summaries of the module metadata, are very useful. Two others are rarely used: /STATISTICS, a summary of the PE file characteristics; and /CLASSLIST, a list of types defined in the module, available for file or console dump only.

Figure 16-3 Selecting file dump options.

All of the disassembly options shown in Figure 16-3 are available as command-line options in ILDASM, but the inverse is not quite true. Appendix D, “IL Assembler and Disassembler Command-Line Options,” contains a complete list of all the command-line options. The following list focuses only on the most important of these options:

The /ADVANCED option is the first item you should specify when invoking the disassembler.
The /UTF8 and /UNICODE options set the encoding of the output file. The default encoding is ANSI.
The /TOKENS option includes hexadecimal token values as comments in the disassembly text.
The /BYTES option includes the hexadecimal representation of IL instructions as comments in the disassembly text.
The /ITEM=<item_description> option limits the disassembly to the specified item: a class or a member method. For example, /ITEM="Foo" dumps the Foo class and all its members, /ITEM="Foo::Bar" dumps all member methods named Bar in the Foo class, and /ITEM="Foo::Bar- (int32(int32, string))" dumps the method int32 Foo::Bar(int32, string). This option has no effect if the disassembler is invoked in graphical mode.
The /VISIBILITY=<vis>[+<vis>*] option limits the disassembly to the items that have the specified visibility and accessibility flags. The <vis> suboptions are three-letter abbreviations of all possible visibility and accessibility flags:
- PUB Public
- PRI Private
- FAM Family
- ASM Assembly
- FAA Family and assembly
- FOA Family or assembly
- PSC Private scope
  
  For example, /VIS=PUB+FAM+FOA limits the disassembly output to only those items that can be accessed from outside the assembly.
The /NOIL option suppresses the ILAsm source text output. You can use this option when you are interested not in a disassembly but in file statistics, a metadata summary, and so on. This option has no effect if the disassembler is invoked in graphical mode.
The /RAWEH option forces all structured exception handling clauses to be dumped in canonic form at the end of each method scope.
The /LINENUM option includes the .language and .line directives in the disassembly text, to allow the reassembled code to be bound to the original source files rather than the ILAsm source file. (The section “Compiling in Debug Mode,” later in this chapter, discusses the use of these directives in detail.) This option has no effect if the PE file being disassembled is not accompanied by a program database (PDB) file that contains all the debug information.
The /NOBAR option suppresses the pop-up window showing the disassembly progress. This option is useful if the disassembler is invoked from batch files as part of an automatic process running in the background.
The /METAINFO[=<met_opt>] option dumps the metadata summary. The <met_opt> suboptions indicate the specifics of this summary:
- HEX Add hexadecimal representation of the signatures
- CSV Provide the sizes of string, blob, and GUID heaps and sizes of the metadata tables and their records
- MDH Provide the metadata header details
- UNR Provide a list of unresolved method references and method definitions without implementation
- VAL Run metadata validation
  
  The metadata suboptions can’t be concatenated using the plus character, as the visibility suboptions can be. Instead, multiple occurrences of /METAINFO options are permitted in order to set multiple suboptions. For example, ildasm /adv /noil /met=hex /met=mdh MyModule.dll /out:MyModule.txt.

All of these options are recognized by their first three letters (/NOBAR means the same as /NOB, for instance) and are case-insensitive (/NOB means the same as /nob). The colon character (:) and the equality character (=) are interchangeable; for example, /vis=pub means the same as /vis:pub.

When a PE file is disassembled in full to a file, the managed and unmanaged resources are automatically saved to respective files so that they can be picked up by the assembler and incorporated into a new PE file during the reassembly. “In full” means that neither /NOIL nor /ITEM nor /VIS options are specified, because these options result in a partial disassembly, whose text is not suitable for reassembling. The unmanaged resources are saved in a file that has the same name as the output file and has the extension RES. The managed resources are saved in files named according to the managed resource names specified in the metadata. The resource files are not saved when a PE file is disassembled to a console window using the option /TEXT or /OUT:CON.