Table 2. Some (but not all) options of ildasm.

To take this tool out for a test drive, let's view the internal structure of the entire client.exe assembly (Listing 11).

ildasm client.exe

The first point of interest is the manifest data, which as you recall is metadata that defines the assembly itself (Listing 12).

.assembly extern mscorlib
{
  .publickeytoken = (B7 7A 5C 56 19 34 E0 89 )
  .ver 1:0:3300:0
}
.assembly extern shamer
{
  .ver 0:0:0:0
}
.assembly client
{
  ...
  .hash algorithm 0x00008004
  .ver 0:0:0:0
}
.module client.exe
.imagebase 0x00400000
.subsystem 0x00000003
.file alignment 512
.corflags 0x00000001

The critical point here is the use of the .assembly extern directives. These CIL token are used to document the set of external assemblies the current assembly must have to function correctly. Notice that client.exe makes use of the standard mscorlib.dll assembly as well as (surprise, surprise) shamer.dll. Next, notice that the .assembly directive (without the extern attribute) is used to describe basic characteristics of the current assembly (client.exe in this case) such as it's version (.ver) and module name (.module). As mentioned, the .NET runtime reads this information during the process of locating and loading external assemblies for use (exactly how is the topic of a later article).

Next, let's examine the CIL code produced by csc for the client's static Main() method (Listing 13). Be aware that each of the IL_XXXX: tokens are line-labels inserted by ildasm.

.method public hidebysig static void 
  Main(string[] args) cil managed
{
  .entrypoint
  .maxstack  2
  .locals init (string V_0, int32 V_1)
  IL_0000:  ldarg.0
  IL_0001:  ldlen
  IL_0002:  conv.i4
  IL_0003:  brfalse.s IL_0014
  IL_0005:  ldarg.0
  IL_0006:  ldc.i4.0
  IL_0007:  ldelem.ref
  IL_0008:  stloc.0
  IL_0009:  ldarg.0
  IL_000a:  ldc.i4.1
  IL_000b:  ldelem.ref
  IL_000c:  call int32 [mscorlib]
    System.Int32::Parse(string)
  IL_0011:  stloc.1
  IL_0012:  br.s IL_0039
  IL_0014:  ldstr "Please enter child's name: "
  IL_0019:  call void [mscorlib]
    System.Console::Write(string)
  IL_001e:  call string [mscorlib]
    System.Console::ReadLine()
  IL_0023:  stloc.0
  IL_0024:  ldstr "Please enter annoyance level: "
  IL_0029:  call void [mscorlib]
    System.Console::Write(string)
  IL_002e:  call string [mscorlib]
    System.Console::ReadLine()
  IL_0033:  call int32 [mscorlib]
    System.Int32::Parse(string)
  IL_0038:  stloc.1
  IL_0039:  ldloc.0
  IL_003a:  ldloc.1
  IL_003b:  call void [shamer]
   ShamerLib.Shamer::ShameChild(string, int32)
  IL_0040:  ldstr "Thanks for playing..."
  IL_0045:  call   void [mscorlib]
    System.Console::WriteLine(string)
  IL_004a:  ret
} // end of method TheApp::Main

Now, before your eyes pop out of your head, let me reiterate that this is not the place to dive into all the details of the syntax of CIL. However, here is a brief explanation of the highlights.

First of all, CIL is an entirely stack based language: values are pushed onto the stack using various CIL operational codes (opcodes) and popped over the stack using others. Notice that the Main() method is adorned with the .entrypoint directive, which as you may guess is how the .NET runtime is able to identify entry point to the executable.

Next, note that the .maxstack directive is used to mark the upper limit of values which may be pushed onto the stack during the duration of this method. Given that our Main() method defines only two local variables and never calls methods with more than two arguments, it should be no surprise the value assigned to .maxstack is 2.

Now, notice the syntax used to invoke a type method (Listing 14).

IL_0019:  call void [mscorlib]
 System.Console::Write(string)
...
IL_003b:  call void [shamer]
 ShamerLib.Shamer::ShameChild(string, int32)

As you can see, the call opcode marks the act of invocating a method. However, notice that the friendly name of the assembly is infixed between the return value and method name. Given this, we can boil down a CIL method invocation to the following simple template shown in Listing 15:

ReturnType[NameOfAssembly]
 Namespace.Type::MethodName(anyArguments)

Again, don't sweat the details of CIL at this point in the game (in fact, you can live the life of a happy and healthy C# developer without thinking about CIL whatsoever). Simply understand that the ildasm tool allows you to view the raw CIL syntax emitted by a given .NET compiler.

Recall that an assembly is composed of three key elements (CIL, type metadata and manifest information). If you wish to view the type metadata within a given assembly, you must specify the /metadata option (Listing 16).

ildasm /metadata client.exe

Once you execute this command, you will find that the initial output of ildasm is indeed a listing of type metadata. Simply put, .NET metadata can be lumped into two categories: TypeDefs (types you defined yourself) and TypeRefs (types within an external assembly you referenced). Both of these categories will list in vivid detail the composition of each item (e.g. base class, number of methods, method parameters, etc). For example, Listing 17 shows the metadata for the ShamerClient.TheApp class type defined within client.exe (again, don't sweat the details).

// TypeDef #1
// ----------------------------------------------
// TypDefName: ShamerClient.TheApp  (02000002)
// Flags : [Public] [AutoLayout] 
//  [Class] [AnsiClass]  (00100001)
// Extends : 01000001 [TypeRef] System.Object
// Method #1 [ENTRYPOINT]
// ----------------------------------------------
// MethodName: Main (06000001)
// Flags : [Public] [Static] 
//  [HideBySig] [ReuseSlot]  (00000096)
// RVA : 0x00002050
// ImplFlags : [IL] [Managed]  (00000000)
// CallCnvntn: [DEFAULT]
// ReturnType: Void
// 1 Arguments
// Argument #1:  SZArray String
// 1 Parameters
// (1) ParamToken : (08000001) Name : 
//  args flags: [none] (00000000)
// 
// Method #2 
// ----------------------------------------------
// MethodName: .ctor (06000002)
// Flags : [Public] [HideBySig] [ReuseSlot] 
//  [SpecialName] [RTSpecialName] [.ctor]  (00001886)
// RVA : 0x000020a8
// ImplFlags : [IL] [Managed]  (00000000)
// CallCnvntn: [DEFAULT]
// hasThis 
// ReturnType: Void
// No arguments.

Now, you may be wondering what use type metadata serves in the .NET platform. To be honest, just about everything in .NET revolves around metadata in one form or another. Object serialization, XML Web services, .NET remoting, late binding, dynamic type creation and heap allocations all demand full type descriptions. Later in this series, you will learn how to leverage this information programmatically using the friendly object model provided by the System.Reflection namespace (can anyone say custom object browser?)

On a metadata-related note, the SSCLI supplies an additional tool (metainfo) which is used exclusively to view type metadata (see /sscli/docs/tools/metainfo.html for full details). For example, if you wish to see the TypeDefs and TypeRefs within shamer.dll (but don't care to see the CIL code or manifest data), you could enter the following command (Listing 18):

metainfo shamer.dll

Now that you can disassemble a .NET assembly using ildasm and metainfo, it is worth pointing out that the SSCLI ships with a CIL assembler utility named (not surprisingly) ilasm. Although it is not terribly likely, it is entirely possible to build an complete .NET application using raw CIL code and bypass higher level languages such as C#, VB.NET and so forth (remember, as far as the .NET runtime is concerned, it's all CIL). As suggested by Table 3, working with ilasm is quite straightforward.

Options of ilasm     Meaning in Life  

/clock               Tells ilasm to display compilation diagnostics for the current build.  

/dll or /exe         Builds a code library or executable assembly (respectively).   

/output              Specifies the name of the output file.      

As a fellow programmer, I'm sure you'd love to build a .NET assembly using CIL and the CIL assembler at least once (just to say you did it). Again, building anything but a trivial CIL source code file would require a solid understanding of the syntax and semantics of the Common Intermediate Language, however if you are up for the task, create a brand new source code file named simpleCILCode.il (by convention, CIL code files take an *.il extension). Within your new file, define the following .NET type (Listing 19):

//  mscorlib.dll is automatically 
// listed in the manifest by ilasm,
// so we don't need to bother specifying
// this external assembly.
// Now defined our assembly. 
// If unspecified, the version
// of an assembly is automatically
// 0.0.0.0.
.assembly SimpleCILCode{}
.module SimpleCILCode.dll
// Our only class type: MyCILExample.MyCILApp
.namespace MyCILExample
{
  .class public auto ansi beforefieldinit MyCILApp
    extends [mscorlib]System.Object 
  {
          // The single method, Speak().
    .method public hidebysig static void 
      Speak() cil managed
    {
      .maxstack 1
      ldstr "Yo!!"
      call void [mscorlib]
        System.Console::WriteLine(string)
      ret
    }         
  }
}

Basically, this CIL code file defines a single namespace (MyCILExample) which contains a single class (MyCILApp) which supports a single method named Speak(). The implementation of Speak() loads a string literal onto the stack (via the ldstr opcode) which is used for the invocation of System.Console.WriteLine(). The ret opcode, obviously, returns from the method. Now, to compile this CIL source code file into a binary *.dll, supply the following command set to ilasm (Listing 20):

ilasm /output: Simple.dll /dll SimpleCILCode.il

At this point, you can make use of Simple.dll just as you would any other .NET code library. To prove the point, let's update our existing simpleClientApplication.cs file to invoke the Speak() method (Listing 21).

using System;
using ShamerLib;
// Need this!
using MyCILExample;
namespace ShamerClient
{
  public class TheApp
  {
    public static void Main(string[] args)
    {
      ...
      MyCILApp.Speak();
    }
  }
}

Now recompile client.exe while referencing simple.dll (Listing 22).

csc /r:simple.dll /r:shamer.dll /t:exe /out:client.exe simpleClientApplication.cs

Sure enough, if you run simpleClientApplicaion.exe through ildasm, you will find Simple.dll listed in the assembly manifest. Likewise, if you run the updated application, you will find that the message ("Yo!!") is emitted to the Terminal.

Given the functionality of ildasm and ilasm, the SSCLI (as well as other .NET platform distributions) intrinsically supports the notion of a 'round trip'. Simply put, this software idiom is used to describe the process of compiling -> decompiling -> editing -> recompiling a software blob into a new modified unit. As you would guess, this can prove extremely helpful when you need to modify the contents of a .NET assembly to which you do not have the original source code files. To solidify the information presented in this issue, try the following round-trip exercise:

• Disassemble your client application using ildasm, outputting the CIL to a new file named simpleClientApplication.il (don't forget the /output flag of ildasm).

• Using your text editor of choice, modify each string literal (e.g. "Please enter child's name") to a new string ("Yo dude! Enter the name of the kid!").

• Save your changes and recompile the *.il file into a new executable assembly named ModifiedApp.exe using ilasm.

• Run your ModifiedApp.exe assembly using clix.

Now obviously, if a .NET assembly can be so easily disassembled, modified and recompiled, you are no likely already imagining numerous doomsday scenarios (your proprietary 'bubble sort' algorithm has been modified to wipe a user's hard-drive of all data) and copyright infringements ("But that is our CIL code, you can't change it!") Yes it is true, given that a .NET binary can always be viewed in terms of its CIL code using tools such as ildasm, it is possible that prying eyes could take your intellectual property as a basic for their own and build a software monster. This problem is not unique to the .NET platform however, as numerous Java, C(++) and BASIC decompilers have existed for years.

However, if you wish to lessen the chances of bad people using your resulting CIL code for evil purposes, rest assured that numerous .NET obfuscators exist. As you may know, the basic role of an obfuscator is to make use of a set of algorithms translate valid syntax (in this case CIL code) into and out-of total nonsense. As well, the .NET platform supports the notion of a 'strong name' which can be used to digitally sign (in effect) your assemblies using public / private key cryptography. By doing so, it is next to impossible for an evil individual to modify a binary assembly and pretend to 'be you'. More on strong names at a later time.

Sweet! So here ends another installment of Casting your .NET where you spent your time digging deeper into the format of a .NET assembly. We began by revisiting the key elements of a .NET binary (CIL, metadata and manifest information) and learned about some additional functionality provided by csc. Next up, you came to understand the role of the ildasm utility and learned how this tool allows .NET developers to peek inside the assembly itself to view the underlying goo. Finally, you took ilasm out for a test drive and preformed a simple 'round-trip'.

In the next issue, you will finalize your initial look at the SSCLI and examine a number of interesting sample applications, alternative .NET programming languages and a few additional development utilities. After this point, the next several installments will dive headlong into the details of the C# programming language. Until then, as always, happy hacking.

Andrew Troelsen is a seasoned .NET developer who has authored numerous books on the topic, including the award winning C# and the .NET Platform. He is employed as a full-time .NET trainer and consultant for Intertech Training (www.intertechtraining.com), and is a well-known Timberwolves, Wild and Vikings rube (not necessarily in that order). You can contact Andrew at atroelsen@mac.com.