DocumentN4

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.netemail: [email protected] availability

Agenda

What Is Metadata?Metadata Object OverviewThe Reflection APIThe Unmanaged APIType Signatures & TokensTools And DemoWrap-up And Resources

Metadata: The Big PictureMetadata is information stored in .NET assemblies that makes them self-describingMetadata describes:

Classes (types) provided by the assemblyMethod and field information for classesVersion informationDependencies on other assemblies and modulesSecurity 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 ConceptCOM IDL files describe interfaces, methods, parameters, and types in sufficient detail to marshal calls between processesCOM Type Libraries are just a binary representation of IDL informationMetadata is effectively type libraries on steroidsMicrosoft 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 runtimeMetadata is stored in a binary format, and subject to changeMicrosoft provides .NET classes and classic COM interfaces to read and write metadata

The Advantage Of MetadataA shared standard of representing information between any .NET compatible language

Cool benefit: Intellisense for any .NET componentMetadata is automatically generated and consumed by .NET compilers

No need to create .IDL files to expose your code to othersNo 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:

AssemblyBuilderMethodBuilderILGeneratorMany more!

Focus in this presentation is consuming metadata

Agenda


The Metadata Hierarchy I

Assembly(e.g., mscorlib)

Modules

Module(i.e., a DLL)

Classes

Global Methods& Variables

Collections

SingleInstances

The Metadata Hierarchy IIClass

(e.g., System.Object)

Methods

Fields

Properties

Events

Method(e.g., “Foo”)

Parameters

Parameter“int Param1”

Parameter“String Param2”

Assembly Metadata

NamePublic keyVersion # (major & minor)Build #Revision #Dependencies on other assembliesLocale

Class Metadata Contents

NameFlags (CorTypeAttr)

Visibility (Public, private, assembly, …)Layout (auto, sequential, explicit…)Type (class, interface, value type, …)

Base class (if applicable)

Method Metadata Contents

NameParent classFlags (CorMethodAttr)

VisibilityStatic / VirtualPlatform Invoke (interop to legacy code)

Implementation Flags (CorMethodImpl)IL / OptIL / NativeManaged / Unmanaged implementation

SignatureRVA to IL in executable file

Parameter Metadata Contents

NameParent methodOrder in method parameter listAttributes (CorParamAttr)

In / OutHas default valueOptional

Field Metadata Contents

NameParent classAttributes (CorFieldAttr)

VisibilityStatic member

Signature (implicitly gives the size)

Property Metadata Contents

NameParent classAttributes (CorPropertyAttr)Signature (implicitly gives the size)Getter & Setter methodsDefault value

Event Metadata Contents

NameParent classFired methodAddOn / RemoveOn methods

Custom Attributes

Custom attributes are special classes that provide additional information about a:

Assembly / ModuleClass / StructMethod / Constructor / PropertyEnumParameter / Field

Unmanaged and Reflection APIs for reading / creating custom attributes

Agenda


About The Reflection API

Full access to metadata using .NET runtime classesAssemblies, classes, methods, fields, etc… are all represented as .NET objectsLayered over the unmanaged metadata interfaces

The Metadata Hierarchy As Seen By The Reflection API

ManifestResource

FieldInfo PropertyInfo

ParameterInfo

MethodInfo EventInfo

Type

Module AssemblyName

Assembly

CustomAttributes

Getting To The Reflection API

There are a variety of entry points into the Reflection classesAssembly::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 hierarchyType::GetMethods, etc… moves down

Demo

ReflectCS program

Example: Enumerating All Methods In An Assembly

Use Assembly::LoadFrom to load a .NET assemblyReturns an Assembly *

Assembly::GetModules returns an array of Module *’sFor each Module *, call Module::GetTypes

Returns an array of Type *’s

For each Type *, call Type::GetMethodsReturns an array of MethodInfo *’s

For each MethodInfo *, the MethodInfo::Nameproperty returns the method’s name

Agenda


About The Unmanaged API

Regular COM interfaces that don’t use the .NET runtimeRelies heavily on “tokens”More granular than equivalent COM ITypeLib & ITypeInfo interfaces

Information isn’t packed into structuresDeclared in COR.H / CORHDR.HCLSIDs and IIDs defined in CORGUID.LIB

The Unmanaged Metadata Interfaces

IMetaDataDispenserThe “root” interface for obtaining all othersWorks on file or memory based metadata

IMetaDataImportThe primary interface for reading class info

IMetaDataAssemblyImportIMetaDataEmitIMetaDataAssemblyEmit

DemoThe Meta program

Obtaining an IMetaDataImportInterface 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 TokensmdTypeDef: A classmdMethodDef: A code member of a classmdParamDef: A parameter to a methodmdFieldDef: A data member of a classmdPropertyDef: Similar to a field, but with accessormethodsmdTypeRef: A reference to a class (possibly in another assembly)mdMemberRef: A reference to a code or data member in another modulemdModuleRef: A reference to another module (possibly in another assembly)

IMetaDataImport MethodsToken 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


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” typesMore complex types (e.g., pointers) are built out of base types and modifiers

Type Signature Example

long FirstFunction( long j, float k);

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

becomes…

Drilling Into Metadata TokensThe DWORD tokens used by the unmanaged interfaces are easily decodedThe top BYTE indicates the token type

See CorTokenType in CORHDR.HThe bottom 3 BYTEs are an array index

Indices start at 0, and increase monotonically through the assemblyThus, a maximum of 24MB of any particular token type in an assembly

Token Examples

Example tokens0x02000034 = The 0x34th TypeDef in the assembly0x06000159 = The 0x159th method in the assembly

typedef enum CorTokenType

{

mdtModule = 0x00000000,

mdtTypeRef = 0x01000000,

mdtTypeDef = 0x02000000,

mdtFieldDef = 0x04000000,

mdtMethodDef = 0x06000000,

…

Agenda


ILDASM

“Intermediate Language Disassembler”Displays IL and metadata for an assemblyDisplays metadata in a nice, graphical hierarchy

But information is not necessarily completeSemi-undocumented /ADV optionDemo

Aisto’s Reflector

A much more complete Metadata viewer than ILDasmDemoLutz Roeder’s “Reflector” shows assembly resources, and lets you save them to a fileDemo 2: Documentation.xsl from Reflectorhttp://www.aisto.com/roeder/dotnet/

MetaInfo

Written in C++ and the unmanaged APIMicrosoft’s most complete metadata toolSources in <.NET SDK>

.\tool developers guide\samples\metainfoDemo

TypeRefViewer

DemoShows imported namespaces / classes / methodsFrom the November 2001 MSDN magazine, including source

Agenda


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)

Documents

DocumentN4