Avoiding DLL Hell: Introducing Application Metadata in the Microsoft .NET Framework

Matt Pietrek

Why Do You Need Metadata?

#using <System.XML.DLL>

Metadata and Load-time Linking

int foo(char *, int)
{
•••
}

int myFoo = foo( "Hello", 42 );

Metadata as an Evolution of IDL

Drilling into the Metadata

DataDirectory[IMAGE_DIRECTORY_ENTRY_COM_DESCRIPTOR].VirtualAddress

The Metadata Hierarchy

Figure 1 The Metadata Hierarchy for Assemblies

      Skipping global methods for the moment, the next logical step down in the metadata hierarchy is types. A typical use of a type from C++, Visual Basic, or the Java language is to represent a class. Other types include enumerations and interfaces. A .NET interface is a logically related set of methods that is not bound to any single implementation. Essentially, they're the same thing as COM interfaces. If it helps, you can mentally substitute the term class for type in the description that follows.
      .NET types only support single inheritance. The type metadata contains information about what type a descendant type extends from. The base type can be defined in the same assembly or in another assembly. Languages that support multiple inheritance (such as C++) need to find some way of representing their additional inheritance information. That topic is far beyond the scope of this article.
      Each metadata type contains zero or more methods, fields, properties, and events. Each of these items has its own metadata that can be read for more details. A method can be either a regular method with a this pointer, or it can be a static method, not associated with any particular instance of a type. A field is a data member of a type. It also can be static (that is, it will be shared across all instances of a particular type).
      Collectively, the union of a type's methods and fields are called its members, and there are metadata APIs for getting common properties of a type's members. However, this information is limited to the details that are common to both methods and fields (such as a name). Other APIs let you get the details specific to a method or field. For instance, a method has a calling convention, while a field doesn't. The method-specific metadata APIs can tell you the calling convention, while the field-specific APIs don't.
      A type property is similar to properties in Visual Basic. That is, a property represents data. Unlike a field, though, accessing a property isn't done by directly reading or writing the property's memory. Instead, special methods with names like get_Foo and set_Foo are used to read and write the property's value. With a compiler that targets .NET, you can refer to a property directly by its name, and the compilers will automatically substitute the correct get_XXX or set_XXX method as necessary. A property can optionally be backed by a field. That is, the memory accessed by the get_ or set_ methods is the same memory used for a field.
      Type events should also be familiar to you if you use Visual Basic. When an object sees that an event has occurred, the object can fire a method call indicating that a specific event has happened. Events support the ability for your code to add or remove requests to be notified when the event occurs. These add or remove requests are made through special methods called AddOn and RemoveOn.
      A type's methods, fields, and properties all have additional information that can be inspected. For starters, they all have some sort of type information. Here, I mean type in the traditional sense such as int, bool, pointer to float, and struct foo. Fields and properties both have a single type associated with them. This information is encoded in a type signature. I'll come back to type signatures later, but for now a type signature is simply a variable-length string of bytes that represent the type.
      Methods are more complex than fields or properties for obvious reasons. Methods don't have a single type associated with them (such as bool). Instead, they have a set of zero or more parameters, with each parameter having its own type. In addition, a method can have a return value that also has an associated type. Metadata allows overloaded methods (two or more methods with the same name, but different parameters). In the metadata, each method of a type has a unique type signature, a scheme similar to the way the C++ compiler uses name decoration.
      There's one small detail about parameters and metadata worth mentioning since it confused the heck out of me at first. A method's type signature includes the number and types of each of the parameters. However, when additional information about a parameter is needed (such as its name or marshaling information), a compiler can emit a parameter definition as well. The metadata parameter definition and type signature are two different views of the same data. You shouldn't rely on parameter definitions being available for methods. However, you can always depend on a method to have a type signature. The type signature is what the runtime uses when resolving a call to a method.

The Two Metadata APIs

Using the Unmanaged Metadata Interfaces

#include <cor.h>
•••
HRESULT hr =
CoCreateInstance(CLSID_CorMetaDataDispenser, 0,
                 CLSCTX_INPROC_SERVER,
                 IID_IMetaDataDispenser,
                 (LPVOID *)&pIMetaDataDispenser );

hr = pIMetaDataDispenser->OpenScope(
                                    wszFileName,
                                    ofRead,
                                    IID_IMetaDataImport,
                                    (LPUNKNOWN *)&pIMetaDataImport );

Metadata Type Signatures

long FirstFunction( long j, float k);
long SecondFunction( long abc, float xyz);

void SomeVoidFunction( long j, float k)
long SomeFunctionWithOneParameter( long j)

<Number of parameters>
<return type value>
<parameter 1>
<parameter 2>
•••
<parameter n>

0x02 0x08 0x08 0x0C

0x02 0x01 0x08 0x0C

0x01 0x08 0x08

<Calling convention>
<Number of parameters >
<return type value>
<parameter 1>
<parameter 2>
•••
<parameter n>

ELEMENT_TYPE_PTR        = 0xf
ELEMENT_TYPE_SZARRAY    = 0x1D

0x0f 0x08

0x1D 0x0C

ELEMENT_TYPE_CLASS    = 0x12

0x12 <0x02000014>

0x1D 0x12 <0x02000014>

The IMetaDataAssemblyImport Interface

Metadata Tokens: Simpler than You Think

struct token
{
BYTE    CorTokenType
BYTE RID[3];
}

#define TypeFromToken(tk) ((ULONG32)((tk) & 0xff000000))

The Reflection API

Assembly
    Module    
    Type
        MethodInfo
            ParameterInfo
        FieldInfo
        EventInfo
        PropertyInfo
    AssemblyName
    ManifestResource (String *)

MethodInfo * arMethodInfo[] = pType->GetMethods();
    
for ( unsigned idx =0; idx < arMethodInfo->Length; idx++ )
{
    ProcessMethodInfo( arMethodInfo[idx] );
}

mdHideBySig
mdReuseSlot
mdNewSlot
mdAbstract
mdSpecialName
mdPinvokeImpl
mdUnmanagedExport
mdRTSpecialName
mdHasSecurity
mdRequireSecObject

Metadata Inspection

Figure 8 mscorlib.dll

      For this article, I'm not interested in the disassembly capabilities of ILDASM. By running "ILDASM /?", you'll get a help screen that displays all of its command-line options. Among the options is the ability to filter which items are shown, using visibility as the criteria. Another option tells ILDASM to write its output to a file, rather than display it in a window.
      Another simpler tool for dumping metadata is MetaInfo.EXE. This tool is included with the PDC Tech Preview build, in the .\NGWSSDK\tool developers guide\samples\metainfo directory. You'll have to build the source to get a runnable .EXE, but it's worth the effort. MetaInfo leaves no stone unturned in its search to hunt down and display every last scrap of information in the metadata.
      To add to the official Microsoft tools, I've written two demo applications for this article. The first program, Meta, uses the unmanaged API. The second, ReflectMeta, uses the Reflection API. Both Meta and ReflectMeta display an assembly's types, methods, fields, and properties. You can download the demos from the link at the top of this article.
      Beyond these basics, Meta and ReflectMeta show different information. For example, type signatures are readily available to the unmanaged API, so Meta displays them. In contrast, type signatures aren't obtainable (to my knowledge) via the Reflection API. Instead, ReflectMeta shows how easy it is to get a human-readable representation of a parameter type. To do the equivalent using the unmanaged APIs in Meta would take hundreds of lines of code.
      Both Meta and ReflectMeta are console-mode applications, written in Visual C++ with managed extensions. For input, they take the name of an assembly file (typically an EXE or DLL), and write their output to the standard out file. Both are intentionally simple, and I didn't labor to display every last scrap of information. Instead, I focused on the big picture and tried to keep the code simple enough to be read easily.
      The Meta program doesn't use the .NET common language runtime. It begins by displaying some basic information about the assembly manifest, including a list of other referenced assemblies. This informa tion comes from the IMetaDataAssemblyImport methods. Next, Meta displays all of the TypeDefs. For each TypeDef, it displays the methods, fields, and properties, along with their tokens and type signature bytes.
      After the TypeDefs, Meta switches to displaying the TypeRefs (that is, types imported from other assemblies). For each TypeRef, the MVID of the referenced assembly is shown along with the mdTypeDef token for the type within the assembly. The last part of each TypeRef is the MemberRefs. A MemberRef represents an individual method, field, or property of the referenced type. Only those items actually used from the type appear in the MemberRef list. The final thing Meta shows is the ModuleRefs, which are the modules to which the assembly contains references. The list will include any non-.NET DLLs that are called via PInvoke.
      The ReflectMeta demo program is much simpler, and uses the .NET common language runtime. I intentionally didn't try to use all the snazzy .NET output and formatting classes, and focused instead on making the code easy to understand. This includes my decision to use printf for output. Since printf isn't a .NET method, the PInvoke mechanism is used to call the printf function exported from MSVCRT.DLL. Other than the spot where I do a sysimport to declare printf, calling printf is just the same as calling a managed method.
      ReflectMeta begins by calling Assembly::Load for the command-line argument. If an invalid file is passed, the method throws an exception, which is handled in main. If a file containing metadata was successfully loaded, the code iterates through all of the modules in the assembly. Typically, each assembly only contains one module.
      For each module, ReflectMeta calls my DumpGlobalMethods function, which displays the module-level methods. Next, ReflectMeta calls Module::GetTypes to get a list of Types in the module. For each Type, the code calls Type::GetMembers, which returns an array of MemberInfo pointers. Each MemberInfo represents a method, constructor, field, or property. Although not well known, a MemberInfo pointer can be downcast to an appropriate MethodInfo, ConstructorInfo, FieldInfo, or PropertyInfo pointer, which you can use to get more detailed information than the MemberInfo class can provide.
      For each MethodInfo instance, ReflectMeta uses MethodInfo:: GetParameters to get an array of ParameterInfo objects. As you can see in the code for my FormatParameterString function, it's trivial to get the parameter's type and name as human-readable strings. Warning: the FormatParameterString code is probably a less than optimal use of the .NET StringBuilder class. At the present time, good examples of string formatting in .NET are difficult to find.
      After enumerating through all the modules and Types, ReflectMeta returns to the manifest-level information available through the Assembly class. It displays the same list of referenced assemblies that you can get from the Meta program. Finally, it displays the resource files that are part of the assembly. Obviously, the ReflectMeta program could be easily extended to do more than it currently does. My goal was simply to touch on most of the major areas available via the Reflection API.

Conclusion