Introduction To .

NET
Metadata
Matt Pietrek
 Housekeeping
Who is this guy?
Co-founder, Mindreef LLC (www.mindreef.com)
President, Wheaty Productions Inc.
MSDN’s “Under the Hood” columnist
web: http://www.wheaty.net
email: matt@wheaty.net
Source availability
Agenda
What Is Metadata?
Metadata Object Overview
The Reflection API
The Unmanaged API
Type Signatures & Tokens
Tools And Demo
Wrap-up And Resources
Metadata: The Big Picture
Metadata is information stored in .NET assemblies
that makes them self-describing
Metadata describes:
Classes (types) provided by the assembly
Method and field information for classes
Version information
Dependencies on other assemblies and modules
Security attributes required
Metadata provides the information that the .NET
runtime needs to ensure type safety and security
Demo: Many Views
Of Metadata
Metadata: Evolution Of A COM Concept
COM IDL files describe interfaces,
methods, parameters, and types in sufficient
detail to marshal calls between processes
COM Type Libraries are just a binary
representation of IDL information
Metadata is effectively type libraries on
steroids
Microsoft provides tools to convert between
metadata and type libraries
Metadata Usage In .NET
The .NET runtime relies heavily on
metadata to link together calls and data
references at runtime
Metadata is stored in a binary format, and
subject to change
Microsoft provides .NET classes and classic
COM interfaces to read and write metadata
The Advantage Of Metadata
A shared standard of representing information
between any .NET compatible language
Cool benefit: Intellisense for any .NET component
Metadata is automatically generated and
consumed by .NET compilers
No need to create .IDL files to expose your code
to others
No need to mess around with .H files and import
libraries
Emitting Metadata
Metadata (and associated IL) can be created using
the .NET runtime
Compilers aren’t the only ones that get to play!
System.Reflection.Emit classes are the basis for
dynamically creating code:
AssemblyBuilder
MethodBuilder
ILGenerator
Many more!
Focus in this presentation is consuming metadata
Agenda
What Is Metadata?
Metadata Object Overview
The Reflection API
The Unmanaged API
Type Signatures & Tokens
Tools And Demo
Wrap-up And Resources
 The Metadata Hierarchy I
Assembly Collections
(e.g., mscorlib)
Single
Instances
Modules

Module
Classes
(i.e., a DLL)

Global Methods
& Variables
 The Metadata Hierarchy II
Class
(e.g., System.Object)

Method
Methods
(e.g., “Foo”)

Fields
Parameters

Properties Parameter
“int Param1”

Events Parameter
“String Param2”
Assembly Metadata
Name
Public key
Version # (major & minor)
Build #
Revision #
Dependencies on other assemblies
Locale
Class Metadata Contents
Name
Flags (CorTypeAttr)
Visibility (Public, private, assembly, …)
Layout (auto, sequential, explicit…)
Type (class, interface, value type, …)
Base class (if applicable)
Method Metadata Contents
Name
Parent class
Flags (CorMethodAttr)
Visibility
Static / Virtual
Platform Invoke (interop to legacy code)
Implementation Flags (CorMethodImpl)
IL / OptIL / Native
Managed / Unmanaged implementation
Signature
RVA to IL in executable file
Parameter Metadata Contents

Name
Parent method
Order in method parameter list
Attributes (CorParamAttr)
In / Out
Has default value
Optional
Field Metadata Contents

Name
Parent class
Attributes (CorFieldAttr)
Visibility
Static member
Signature (implicitly gives the size)
Property Metadata Contents

Name
Parent class
Attributes (CorPropertyAttr)
Signature (implicitly gives the size)
Getter & Setter methods
Default value
Event Metadata Contents

Name
Parent class
Fired method
AddOn / RemoveOn methods
Custom Attributes
Custom attributes are special classes that
provide additional information about a:
Assembly / Module
Class / Struct
Method / Constructor / Property
Enum
Parameter / Field
Unmanaged and Reflection APIs for
reading / creating custom attributes
Agenda
What Is Metadata?
Metadata Object Overview
The Reflection API
The Unmanaged API
Type Signatures & Tokens
Tools And Demo
Wrap-up And Resources
About The Reflection API
Full access to metadata using .NET runtime
classes
Assemblies, classes, methods, fields, etc…
are all represented as .NET objects
Layered over the unmanaged metadata
interfaces
 The Metadata Hierarchy As Seen By
The Reflection API
Assembly

ManifestResource Module AssemblyName

Type
Custom
Attributes
FieldInfo PropertyInfo

MethodInfo EventInfo

ParameterInfo
Getting To The Reflection API
There are a variety of entry points into the
Reflection classes
Assembly::LoadFrom loads a file based
assembly
Returns an Assembly *
For an existing .NET object, use the
::GetType method to get a Type*
Type::Module property moves up the hierarchy
Type::GetMethods, etc… moves down
 Demo
ReflectCS program
 Example: Enumerating All Methods
In An Assembly
Use Assembly::LoadFrom to load a .NET assembly
Returns an Assembly *
Assembly::GetModules returns an array of Module *’s
For each Module *, call Module::GetTypes
Returns an array of Type *’s
For each Type *, call Type::GetMethods
Returns an array of MethodInfo *’s
For each MethodInfo *, the MethodInfo::Name
property returns the method’s name
Agenda
What Is Metadata?
Metadata Object Overview
The Reflection API
The Unmanaged API
Type Signatures & Tokens
Tools And Demo
Wrap-up And Resources
About The Unmanaged API

Regular COM interfaces that don’t use the

.NET runtime
Relies heavily on “tokens”
More granular than equivalent COM
ITypeLib & ITypeInfo interfaces
Information isn’t packed into structures
Declared in COR.H / CORHDR.H
CLSIDs and IIDs defined in
CORGUID.LIB
The Unmanaged Metadata Interfaces

IMetaDataDispenser
The “root” interface for obtaining all others
Works on file or memory based metadata
IMetaDataImport
The primary interface for reading class info
IMetaDataAssemblyImport
IMetaDataEmit
IMetaDataAssemblyEmit
 Demo
The Meta program
 Obtaining an IMetaDataImport
Interface Instance
#include <cor.h>
CoCreateInstance( CLSID_CorMetaDataDispenser, 0,
CLSCTX_INPROC_SERVER,
IID_IMetaDataDispenser,
(LPVOID *)&pIMetaDataDispenser );

pIMetaDataDispenser->OpenScope(
szFileName, // Name of assembly file
ofRead,
IID_IMetaDataImport,// Desired interface
(LPUNKNOWN *)&pIMetaDataImport );
Important Metadata Tokens
mdTypeDef: A class
mdMethodDef: A code member of a class
mdParamDef: A parameter to a method
mdFieldDef: A data member of a class
mdPropertyDef: Similar to a field, but with accessor
methods
mdTypeRef: A reference to a class (possibly in
another assembly)
mdMemberRef: A reference to a code or data
member in another module
mdModuleRef: A reference to another module
(possibly in another assembly)
IMetaDataImport Methods
Token Enumeration Method Get Properties method

mdTypeDef EnumTypeDefs GetTypeDefProps

mdMethodDef EnumMethods GetMethodProps
mdFieldDef EnumFields GetFieldProps
mdEvent EnumEvents GetEventProps
mdParamDef EnumParams GetParamProps
mdToken EnumMembers GetMemberProps
mdProperty EnumProperties GetPropertyProps
mdMemberRef EnumMemberRefs GetMemberRefProps
mdModuleRef EnumModuleRefs GetModuleRefProps
mdTypeRef EnumTypeRefs GetTypeRefProps
mdPermission EnumPermissionSets GetPermissionSetProps
mdString EnumUserStrings GetUserString
mdCustomValue EnumCustomAttributes GetCustomAttributeProps
mdInterfaceImpl EnumInterfaceImpls GetInterfaceImplProps

This List Is Not Complete!

Example: Enumerating All Methods
In An Assembly
::EnumTypeDefs returns an array of
mdTypeDefs
Each representing one class
::GetTypeDefProps returns the name of the
class (and other assorted info)
Pass each mdTypeDef to ::EnumMethods to
get an array of mdMethodDefs
One per method in the class
::GetMethodProps returns the name of the
method (and other assorted info)
Agenda
What Is Metadata?
Metadata Object Overview
The Reflection API
The Unmanaged API
Type Signatures & Tokens
Tools And Demo
Wrap-up And Resources
 Type Signatures
Signatures are very similar in concept to C++
name mangling
They both provide a minimal level assurance that
the calling code matches up with the called code
In .NET, all methods and fields have a
signature associated with them
.NET signatures are a sequence of bytes that
describe “type” information and other details
For example, the return value and parameter types
of a method
Type Signature Encoding
Format for methods:
Calling convention (BYTE)
Number of parameters (BYTE)
Return value type (Variable length)
Parameter types (Variable length)
CorElementType enum in CORHDR.H
defines “base” types
More complex types (e.g., pointers) are
built out of base types and modifiers
 Type Signature Example
long FirstFunction( long j, float k);

becomes…

0x00 CorCallingConvention::IMAGE_CEE_CS_CALLCONV_DEFAULT

0x02 Number of parameters

0x08 Return type: CorElementType::ELEMENT_TYPE_I4
0x08 Param 1 type: CorElementType::ELEMENT_TYPE_I4
0x0C Param 2 type: CorElementType::ELEMENT_TYPE_R4
Drilling Into Metadata Tokens
The DWORD tokens used by the
unmanaged interfaces are easily decoded
The top BYTE indicates the token type
See CorTokenType in CORHDR.H
The bottom 3 BYTEs are an array index
Indices start at 0, and increase monotonically
through the assembly
Thus, a maximum of 24MB of any particular
token type in an assembly
 Token Examples
typedef enum CorTokenType
{
mdtModule = 0x00000000,
mdtTypeRef = 0x01000000,
mdtTypeDef = 0x02000000,
mdtFieldDef = 0x04000000,
mdtMethodDef = 0x06000000,

…
Example tokens
0x02000034 = The 0x34th TypeDef in the assembly
0x06000159 = The 0x159th method in the assembly
Agenda
What Is Metadata?
Metadata Object Overview
The Reflection API
The Unmanaged API
Type Signatures & Tokens
Tools And Demo
Wrap-up And Resources
ILDASM
“Intermediate Language Disassembler”
Displays IL and metadata for an assembly
Displays metadata in a nice, graphical
hierarchy
But information is not necessarily complete
Semi-undocumented /ADV option
Demo
Aisto’s Reflector
A much more complete Metadata viewer
than ILDasm
Demo
Lutz Roeder’s “Reflector” shows assembly
resources, and lets you save them to a file
Demo 2: Documentation.xsl from Reflector
http://www.aisto.com/roeder/dotnet/
MetaInfo
Written in C++ and the unmanaged API
Microsoft’s most complete metadata tool
Sources in <.NET SDK>
.\tool developers guide\samples\metainfo
Demo
TypeRefViewer
Demo
Shows imported namespaces / classes /
methods
From the November 2001 MSDN
magazine, including source
Agenda
What Is Metadata?
Metadata Object Overview
The Reflection API
The Unmanaged API
Type Signatures & Tokens
Tools And Demo
Wrap-up And Resources
 Wrap-up And Resources
.NET SDK
.\include\cor.h, .\include\corhdr.h
.\tool developers guide\samples\metainfo
.\tool developers guide\docs\
• “Assembly Metadata Unmanaged API.doc”
• “Metadata Unmanaged API.doc”
Reflector program: http://www.aisto.com/roeder/dotnet/
Avoiding DLL Hell, Matt Pietrek, October 2000 MSDN
magazine (Meta program)
March 20001 MSDN magazine (MetaViewer)
November 2001 MSDN magazine (TypeRefViewer)