Assemblies and Modules

CCI Metadata

CCI represents assemblies in the mutable metadata model as Microsoft.Cci.MutableCodeModel.Assembly objects. The equivalent immutable representation is the Microsoft.Cci.IAssembly interface. There are two primary ways to create an Assembly object:
  • Create a new object from scratch.
  • Load an existing assembly or module to create an immutable representation of the assembly, and then create a mutable copy of the original.

Create a New Assembly

Applications sometimes construct assemblies from scratch by creating a new Assembly object, and then using the mutable code model to add metadata and method bodies to the assembly. The HelloIL sample is a simple example of such an application.

Assembly has only a default constructor, but you must initialize several properties. The following example from HelloIL shows typical property settings:
var assembly = new Assembly() {
  Name = nameTable.GetNameFor("Hello"),
  ModuleName = nameTable.GetNameFor("hello.exe"),
  Kind = ModuleKind.ConsoleApplication,
  TargetRuntimeVersion = coreAssembly.TargetRuntimeVersion,
};

The following sections discuss the four properties.
Assembly and Module Names
Assemblies have a name and a module name, which are typically related but not identical.
  • The assembly name is usually a simple string. For this example, the assembly name is “hello”.
  • The Module name is usually the assembly name with an appropriate extension. HelloIL is a console application, so the module name is “hello.exe”.
Note: Names are represented by an IName interface and should be in the NameTable object. The standard way to obtain an IName interface is to pass the string to NameTable.GetNameFor, which adds the name to the table if necessary and returns an appropriate IName interface.
Module Kind
Assemblies can be any of the following five types, which are represented by values from the Microsoft.Cci.ModuleKind enumeration (in parentheses).
  • Console application (ConsoleApplication): an executable file with an entry point and a console.
  • Windows application (WindowsApplication): an executable file with an entry point but no console.
  • DLL (DynamicallyLinkedLibrary): a dynamically linked library of .NET executable code with no entry point.
  • Unmanaged DLL (UnmanagedDynamicallyLinkedLibrary): a dynamically linked library of unmanaged executable code with no entry point. Unmanaged DLLs are processor-specific and contain no .NET metadata.
  • Resource file (ManifestResourceFile): a file that contains a resource stream, but no executable code.
The example is a console application, so Kind is set to ModuleKind.ConsoleApplication.
Runtime Target Version
The RuntimeTargetVersion property specifies the targeted CLR version. Typically, the exact version number is not important, but you still must provide a valid version string. The example takes the simplest approach and sets RuntimeTargetVersion to the version string from the loaded version of mscorlib.dll.

Usually, mscorlib.dll is unified with the latest .NET version on your system. For example, if you specify version 1.1 but you have version 2.0 on your system, .NET uses version 2.0. Although unification is suitable for many applications, there are times when you might want to force .NET to use a particular version, such as:
  • To ensure that an application does not use an API element that was introduced in a later version.
  • To build an assembly to run on the .NET compact framework with a specified version of mscorlib.dll.
  • To analyze an assembly that targets a version that is not yet installed on your computer. The assembly won’t run, but you can still analyze it.
The decision to use unification is a matter of application policy, so it is one of the host’s policy settings. DefaultHost specifies unification. To force .NET to use a particular CLR version, you must implement a custom host.

Last edited Mar 17, 2010 at 3:14 PM by Guy_Smith, version 7

Comments

No comments yet.