mono-api-metadata.html

Metadata Reading

The Metadata API gives developers low-level access to the information encoded in CLI modules: type and methods definitions encoded in metadata as well as access to the CIL code and embedded resources.

Managed developers access this information using either the System.Reflection API or a library like Cecil.

To start using the Metadata API it is necessary to open an assembly or a CIL image (a .dll or .exe file) using one of the CIL image opening API calls.

Metadata Heaps

ECMA CLI images contain four heaps that store different kinds of information, these are:

GUID heap (called #GUID) contains 128-bit GUIDs, you can get pointer to a GUID value by calling mono_metadata_guid_heap.
User string heap (called #US), it contains user visible strings, you can fetch a string from this heap by calling mono_metadata_user_string.
Blob heap (called #blob), it contains binary blobs of data, you can get a blob by mono_metadata_blob_heap. You can determine the size of the blob using the mono_metadata_decode_blob_size.

The ECMA file format also has an extra section called the "#~" stream, this stream is the one that holds the metadata tables. There is a high-level API to get access to the contents of this API, described in the section Metadata Tables.

mono_metadata_guid_heap

const char * mono_metadata_guid_heap (MonoImage *meta, guint32 index)

Parameters

meta:
metadata context
index:
index into the guid heap.

Returns

an in-memory pointer to the index in the guid heap.

mono_metadata_string_heap

const char * mono_metadata_string_heap (MonoImage *meta, guint32 index)

Parameters

meta:
metadata context
index:
index into the string heap.

Returns

an in-memory pointer to the index in the string heap.

mono_metadata_blob_heap

const char * mono_metadata_blob_heap (MonoImage *meta, guint32 index)

Parameters

meta:
metadata context
index:
index into the blob.

Returns

an in-memory pointer to the index in the Blob heap.

mono_metadata_user_string

const char * mono_metadata_user_string (MonoImage *meta, guint32 index)

Parameters

meta:
metadata context
index:
index into the user string heap.

Returns

an in-memory pointer to the index in the user string heap ("US").

mono_metadata_decode_blob_size

guint32 mono_metadata_decode_blob_size (const char *xptr, const char **rptr)

Parameters

ptr:
pointer to a blob object
rptr:
the new position of the pointer

Returns

the size of the blob object

Remarks

This decodes a compressed size as described by 23.1.4 (a blob or user string object)

Metadata Tables

Metadata is encoded in a number of tables included on every CIL image. These tables contain type definitions, member definitions and so on, these constants are defined in the ECMA 335 specification Partition II section 22. The following table shows the C constants defined in the Mono runtime and how they map to the equivalent ECMA CLI metadata table:

ECMA CLI Table Name	C Constant Name	Table Schema (Array Size + Columns Constants)
Assembly	MONO_TABLE_ASSEMBLY	Array size: MONO_ASSEMBLY_SIZE MONO_ASSEMBLY_HASH_ALG MONO_ASSEMBLY_MAJOR_VERSION MONO_ASSEMBLY_MINOR_VERSION MONO_ASSEMBLY_BUILD_NUMBER MONO_ASSEMBLY_REV_NUMBER MONO_ASSEMBLY_FLAGS MONO_ASSEMBLY_PUBLIC_KEY MONO_ASSEMBLY_NAME MONO_ASSEMBLY_CULTURE	AssemblyOS	MONO_TABLE_ASSEMBLYOS	Array size: MONO_ASSEMBLYOS_SIZE MONO_ASSEMBLYOS_PLATFORM MONO_ASSEMBLYOS_MAJOR_VERSION MONO_ASSEMBLYOS_MINOR_VERSION	AssemblyProcessor	MONO_TABLE_ASSEMBLYPROCESSOR	Array size: MONO_ASSEMBLYPROCESSOR_SIZE MONO_ASSEMBLY_PROCESSOR	AssemblyRef	MONO_TABLE_ASSEMBLYREF	Array size: MONO_ASSEMBLYREF_SIZE MONO_ASSEMBLYREF_MAJOR_VERSION MONO_ASSEMBLYREF_MINOR_VERSION MONO_ASSEMBLYREF_BUILD_NUMBER MONO_ASSEMBLYREF_REV_NUMBER MONO_ASSEMBLYREF_FLAGS MONO_ASSEMBLYREF_PUBLIC_KEY MONO_ASSEMBLYREF_NAME MONO_ASSEMBLYREF_CULTURE MONO_ASSEMBLYREF_HASH_VALUE	AssemblyRefProcessor	MONO_TABLE_ASSEMBLYREFPROCESSOR	Array size: MONO_ASSEMBLYREFPROC_SIZE MONO_ASSEMBLYREFPROC_PROCESSOR MONO_ASSEMBLYREFPROC_ASSEMBLYREF	AssemblyRefOS	MONO_TABLE_ASSEMBLYREFOS	Array size: MONO_ASSEMBLYREFOS_SIZE MONO_ASSEMBLYREFOS_PLATFORM MONO_ASSEMBLYREFOS_MAJOR_VERSION MONO_ASSEMBLYREFOS_MINOR_VERSION MONO_ASSEMBLYREFOS_ASSEMBLYREF	ClassLayout	MONO_TABLE_CLASSLAYOUT	Array size: MONO_CLASSLAYOUT_SIZE MONO_CLASS_LAYOUT_PACKING_SIZE MONO_CLASS_LAYOUT_CLASS_SIZE MONO_CLASS_LAYOUT_PARENT	Constant	MONO_TABLE_CONSTANT	Array size: MONO_CONSTANT_SIZE MONO_CONSTANT_TYPE MONO_CONSTANT_PADDING MONO_CONSTANT_PARENT MONO_CONSTANT_VALUE	CustomAttribute	MONO_TABLE_CUSTOMATTRIBUTE	Array size: MONO_CUSTOM_ATTR_SIZE MONO_CUSTOM_ATTR_PARENT MONO_CUSTOM_ATTR_TYPE MONO_CUSTOM_ATTR_VALUE	DeclSecurity	MONO_TABLE_DECLSECURITY	Array size: MONO_DECL_SECURITY_SIZE MONO_DECL_SECURITY_ACTION MONO_DECL_SECURITY_PARENT MONO_DECL_SECURITY_PERMISSIONSET	EventMap	MONO_TABLE_EVENTMAP	Array size: MONO_EVENT_MAP_SIZE MONO_EVENT_MAP_PARENT MONO_EVENT_MAP_EVENTLIST	EventPtr	MONO_TABLE_EVENT_POINTER	Array size: MONO_EVENT_POINTER_SIZE MONO_EVENT_POINTER_EVENT	Event	MONO_TABLE_EVENT	Array size: MONO_EVENT_SIZE MONO_EVENT_FLAGS MONO_EVENT_NAME MONO_EVENT_TYPE	ExportedType	MONO_TABLE_EXPORTEDTYPE	Array size: MONO_EXPORTEDTYPE_SIZE MONO_EXP_TYPE_FLAGS MONO_EXP_TYPE_TYPEDEF MONO_EXP_TYPE_NAME MONO_EXP_TYPE_NAMESPACE MONO_EXP_TYPE_IMPLEMENTATION	Field	MONO_TABLE_FIELD	Array size: MONO_FIELD_SIZE MONO_FIELD_FLAGS MONO_FIELD_NAME MONO_FIELD_SIGNATURE	FieldLayoutt	MONO_TABLE_FIELDLAYOUT	Array size: MONO_FIELDLAYOUT_SIZE MONO_FIELD_LAYOUT_OFFSET MONO_FIELD_LAYOUT_FIELD	FieldMarshal	MONO_TABLE_FIELDMARSHAL	Array size: MONO_FIELD_MARSHAL_SIZE MONO_FIELD_MARSHAL_PARENT MONO_FIELD_MARSHAL_NATIVE_TYPE	FieldPtr	MONO_TABLE_FIELD_POINTER	Array size: MONO_FIELD_POINTER_SIZE MONO_FIELD_POINTER_FIELD	FieldRVA	MONO_TABLE_FIELDRVA	Array size: MONO_FIELDRVA_SIZE MONO_FIELD_RVA_RVA MONO_FIELD_RVA_FIELD	File	MONO_TABLE_FILE	Array size: MONO_FILE_SIZE MONO_FILE_FLAGS MONO_FILE_NAME MONO_FILE_HASH_VALUE	GenericParam	MONO_TABLE_GENERICPARAM	Array size: MONO_GENERICPARAM_SIZE MONO_GENERICPARAM_NUMBER MONO_GENERICPARAM_FLAGS MONO_GENERICPARAM_OWNER MONO_GENERICPARAM_NAME	GenericParamConstraint	MONO_TABLE_GENERICPARAMCONSTRAINT	Array size: MONO_GENERICPARAMCONSTRAINT_SIZE MONO_GENPARCONSTRAINT_GENERICPAR MONO_GENPARCONSTRAINT_CONSTRAINT
ImplMap	MONO_TABLE_IMPLMAP	Array size: MONO_IMPLMAP_SIZE MONO_IMPLMAP_FLAGS MONO_IMPLMAP_MEMBER MONO_IMPLMAP_NAME MONO_IMPLMAP_SCOPE
InterfaceImpl	MONO_TABLE_INTERFACEIMPL	Array size: MONO_INTERFACEIMPL_SIZE MONO_INTERFACEIMPL_CLASS MONO_INTERFACEIMPL_INTERFACE	ManifestResource	MONO_TABLE_MANIFESTRESOURCE	Array size: MONO_MANIFESTRESOURCE_SIZE MONO_MANIFEST_OFFSET MONO_MANIFEST_FLAGS MONO_MANIFEST_NAME MONO_MANIFEST_IMPLEMENTATION
MemberRef	MONO_TABLE_MEMBERREF	Array size: MONO_MEMBERREF_SIZE MONO_MEMBERREF_CLASS MONO_MEMBERREF_NAME MONO_MEMBERREF_SIGNATURE
MethodImpl	MONO_TABLE_METHODIMPL	Array size: MONO_METHODIMPL_SIZE MONO_METHODIMPL_CLASS MONO_METHODIMPL_BODY MONO_METHODIMPL_DECLARATION	MethodSpec	MONO_TABLE_METHODSPEC	Array size: MONO_METHODSPEC_SIZE MONO_METHODSPEC_METHOD MONO_METHODSPEC_SIGNATURE
MethodSemantics	MONO_TABLE_METHODSEMANTICS	Array size: MONO_METHOD_SEMA_SIZE MONO_METHOD_SEMA_SEMANTICS MONO_METHOD_SEMA_METHOD MONO_METHOD_SEMA_ASSOCIATION
Moduleref	MONO_TABLE_MODULEREF	Array size: MONO_MODULEREF_SIZE MONO_MODULEREF_NAME
Module	MONO_TABLE_MODULE	Array size: MONO_MODULE_SIZE Columns: MONO_MODULE_GENERATION MONO_MODULE_NAME MONO_MODULE_MVID MONO_MODULE_ENC MONO_MODULE_ENCBASE
TypeRef	MONO_TABLE_TYPEREF	Array size: MONO_TYPEREF_SIZE MONO_TYPEREF_SCOPE MONO_TYPEREF_NAME MONO_TYPEREF_NAMESPACE
MethodPtr	MONO_TABLE_METHOD_POINTER	Array size: MONO_METHOD_POINTER_SIZE MONO_METHOD_POINTER_METHOD
Method	MONO_TABLE_METHOD	Array size: MONO_METHOD_SIZE MONO_METHOD_RVA MONO_METHOD_IMPLFLAGS MONO_METHOD_FLAGS MONO_METHOD_NAME MONO_METHOD_SIGNATURE MONO_METHOD_PARAMLIST
NestedClass	MONO_TABLE_NESTEDCLASS	Array size: MONO_NESTEDCLASS_SIZE MONO_NESTED_CLASS_NESTED MONO_NESTED_CLASS_ENCLOSING
ParamPtr	MONO_TABLE_PARAM_POINTER	Array size: MONO_PARAM_POINTER_SIZE MONO_PARAM_POINTER_PARAM
Param	MONO_TABLE_PARAM	Array size: MONO_PARAM_SIZE MONO_PARAM_FLAGS MONO_PARAM_SEQUENCE MONO_PARAM_NAME	PropertyMap	MONO_TABLE_PROPERTYMAP	Array size: MONO_PROPERTY_MAP_SIZE MONO_PROPERTY_MAP_PARENT MONO_PROPERTY_MAP_PROPERTY_LIST	PropertyPtr	MONO_TABLE_PROPERTY_POINTER	Array size: MONO_PROPERTY_POINTER_SIZE MONO_PROPERTY_POINTER_PROPERTY	Property	MONO_TABLE_PROPERTY	Array size: MONO_PROPERTY_SIZE MONO_PROPERTY_FLAGS MONO_PROPERTY_NAME MONO_PROPERTY_TYPE
StandaloneSig	MONO_TABLE_STANDALONESIG	Array size: MONO_STAND_ALONE_SIGNATURE_SIZE MONO_STAND_ALONE_SIGNATURE
TypeDef	MONO_TABLE_TYPEDEF	Array size: MONO_TYPEDEF_SIZE MONO_TYPEDEF_FLAGS MONO_TYPEDEF_NAME MONO_TYPEDEF_NAMESPACE MONO_TYPEDEF_EXTENDS MONO_TYPEDEF_FIELD_LIST MONO_TYPEDEF_METHOD_LIST
TypeSpec	MONO_TABLE_TYPESPEC	Array size: MONO_TYPESPEC_SIZE MONO_TYPESPEC_SIGNATURE

Each table can contain zero or more rows, you must call the mono_metadata_table_rows to obtain the number of rows in a table, and then you can extract individual row values by using the mono_metadata_decode_row or the mono_metadata_decode_row_col. When decoding rows you must provide an guint32 array large enough to hold as many columns as the table contains.

The metadata tables are stored in the MonoImage, you obtain a pointer to the MonoTableInfo by calling the mono_image_get_table_info and then you can scan those tables, for example:

	/*
	 * Dumps a few fields from the AssemblyRef table
	 */
	void DumpAssemblyRefs (MonoImage *image)
	{
		/* Get a pointer to the AssemblyRef metadata table */
		MonoTableInfo *t = mono_image_get_table_info (image, MONO_TABLE_ASSEMBLYREF);

		/* Fetch the number of rows available in the table */
		int rows = mono_table_info_get_rows (t);
		int i;

		/* For each row, print some of its values */
		for (i = 0; i < rows; i++){
			/* Space where we extract one row from the metadata table */
			guint32 cols [MONO_ASSEMBLYREF_SIZE];

			/* Extract the row into the array cols */
			mono_metadata_decode_row (t, i, cols, MONO_ASSEMBLYREF_SIZE);

			fprintf (output, "%d: Version=%d.%d.%d.%d\n\tName=%s\n", i + 1,
                        	cols [MONO_ASSEMBLYREF_MAJOR_VERSION],
                        	cols [MONO_ASSEMBLYREF_MINOR_VERSION],
                        	cols [MONO_ASSEMBLYREF_BUILD_NUMBER],
                        	cols [MONO_ASSEMBLYREF_REV_NUMBER],
                        	mono_metadata_string_heap (image, cols [MONO_ASSEMBLYREF_NAME]));
		}
	}

The above program shows the following output when ran on the C# compiler:

	1: Version=1.0.5000.0
		Name=mscorlib
	2: Version=1.0.5000.0
		Name=System
	3: Version=1.0.5000.0
		Name=System.Xml

Metadata Tables API

These are the APIs for dealing with tables:

mono_image_get_table_info

Prototype: mono_image_get_table_info

mono_image_get_table_rows

Prototype: mono_image_get_table_rows

mono_metadata_get_table

Prototype: mono_metadata_get_table

mono_metadata_decode_row_col

guint32 mono_metadata_decode_row_col (const MonoTableInfo *t, int idx, guint col)

Parameters

t:
table to extract information from.
idx:
index for row in table.
col:
column in the row.

Remarks

This function returns the value of column col from the idx row in the table t.

mono_metadata_decode_row

void mono_metadata_decode_row (const MonoTableInfo *t, int idx, guint32 *res, int res_size)

Parameters

t:
table to extract information from.
idx:
index in table.
res:
array of res_size cols to store the results in

Remarks

This decompresses the metadata element idx in table t into the guint32 res array that has res_size elements

mono_metadata_compute_size

Prototype: mono_metadata_compute_size

mono_metadata_custom_attrs_from_index

Prototype: mono_metadata_custom_attrs_from_index

mono_metadata_decode_signed_value

gint32 mono_metadata_decode_signed_value (const char *ptr, const char **rptr)

Parameters

ptr:
pointer to decode from
rptr:
the new position of the pointer

Returns

the decoded value

Remarks

This routine decompresses 32-bit signed values (not specified in the spec)

mono_metadata_decode_value

guint32 mono_metadata_decode_value (const char *_ptr, const char **rptr)

Parameters

ptr:
pointer to decode from
rptr:
the new position of the pointer

Returns

the decoded value

Remarks

This routine decompresses 32-bit values as specified in the "Blob and Signature" section (22.2)

mono_metadata_encode_value

Prototype: mono_metadata_encode_value

Metadata access API

This is the low-level API for accessing the metadata images.

mono_cli_rva_image_map

Prototype: mono_cli_rva_image_map

mono_pe_file_open

MonoImage* mono_pe_file_open (const char *fname, MonoImageOpenStatus *status)

Parameters

fname:
filename that points to the module we want to open
status:
An error condition is returned in this field

Returns

An open image of type %MonoImage or NULL on error. if NULL, then check the value of status for details on the error. This variant for mono_image_open DOES NOT SET UP CLI METADATA. It's just a PE file loader, used for FileVersionInfo. It also does not use the image cache.

mono_metadata_events_from_typedef

Prototype: mono_metadata_events_from_typedef

mono_metadata_field_info

Prototype: mono_metadata_field_info

mono_metadata_free_array

Prototype: mono_metadata_free_array

mono_metadata_free_marshal_spec

Prototype: mono_metadata_free_marshal_spec

mono_metadata_free_mh

Prototype: mono_metadata_free_mh

mono_metadata_free_type

Prototype: mono_metadata_free_type

mono_metadata_get_constant_index

Prototype: mono_metadata_get_constant_index

mono_metadata_get_marshal_info

Prototype: mono_metadata_get_marshal_info

mono_metadata_implmap_from_method

Prototype: mono_metadata_implmap_from_method

mono_metadata_interfaces_from_typedef

Prototype: mono_metadata_interfaces_from_typedef

mono_metadata_locate

const char * mono_metadata_locate (MonoImage *meta, int table, int idx)

Parameters

meta:
metadata context
table:
table code.
idx:
index of element to retrieve from table.

Returns

a pointer to the idx element in the metadata table whose code is table.

mono_metadata_locate_token

const char * mono_metadata_locate_token (MonoImage *meta, guint32 token)

Parameters

meta:
metadata context
token:
metadata token

Returns

a pointer to the data in the metadata represented by the token token.

mono_metadata_methods_from_event

Prototype: mono_metadata_methods_from_event

mono_metadata_methods_from_property

Prototype: mono_metadata_methods_from_property

mono_metadata_nested_in_typedef

Prototype: mono_metadata_nested_in_typedef

mono_metadata_nesting_typedef

Prototype: mono_metadata_nesting_typedef

mono_metadata_packing_from_typedef

Prototype: mono_metadata_packing_from_typedef

mono_metadata_properties_from_typedef

Prototype: mono_metadata_properties_from_typedef

mono_metadata_token_from_dor

Prototype: mono_metadata_token_from_dor

mono_metadata_typedef_from_field

guint32 mono_metadata_typedef_from_field (MonoImage *meta, guint32 index)

Parameters

meta:
metadata context
index:
FieldDef token

Returns

the 1-based index into the TypeDef table of the type that declared the field described by index, or 0 if not found.

mono_metadata_typedef_from_method

Prototype: mono_metadata_typedef_from_method

mono_metadata_type_equal

Prototype: mono_metadata_type_equal

mono_metadata_type_hash

Prototype: mono_metadata_type_hash

mono_metadata_declsec_from_index

Prototype: mono_metadata_declsec_from_index

mono_metadata_free_method_signature

Prototype: mono_metadata_free_method_signature

Retrieving Objects from Tokens

mono_metadata_parse_custom_mod

Prototype: mono_metadata_parse_custom_mod

mono_metadata_parse_field_type

MonoType* mono_metadata_parse_field_type (MonoImage *m, short field_flags, const char *ptr, const char **rptr)

Parameters

m:
metadata context to extract information from
ptr:
pointer to the field signature
rptr:
pointer updated to match the end of the decoded stream

Returns

The MonoType that was extracted from ptr.

Remarks

Parses the field signature, and returns the type information for it.

mono_metadata_parse_marshal_spec

Prototype: mono_metadata_parse_marshal_spec

mono_metadata_parse_method_signature_full

Prototype: mono_metadata_parse_method_signature_full

mono_metadata_parse_method_signature

Prototype: mono_metadata_parse_method_signature

mono_metadata_parse_mh_full

Prototype: mono_metadata_parse_mh_full

mono_metadata_parse_mh

Prototype: mono_metadata_parse_mh

mono_metadata_parse_param

MonoType* mono_metadata_parse_param (MonoImage *m, const char *ptr, const char **rptr)

Parameters

m:
metadata context to extract information from
ptr:
pointer to the param signature
rptr:
pointer updated to match the end of the decoded stream

Returns

The MonoType that was extracted from ptr.

Remarks

Parses the param signature, and returns the type information for it.

mono_metadata_parse_signature

Prototype: mono_metadata_parse_signature

mono_metadata_parse_typedef_or_ref

Prototype: mono_metadata_parse_typedef_or_ref

mono_metadata_parse_type_full

Prototype: mono_metadata_parse_type_full

mono_metadata_parse_type

static MonoType* mono_metadata_parse_type_internal (MonoImage *m, MonoGenericContainer *container, short opt_attrs, gboolean transient, const char *ptr, const char **rptr)

Parameters

m:
metadata context
mode:
king of type that may be found at ptr
opt_attrs:
optional attributes to store in the returned type
ptr:
pointer to the type representation
rptr:
pointer updated to match the end of the decoded stream
transient:
whenever to allocate the result from the heap or from a mempool

Returns

a MonoType structure representing the decoded type.

Remarks

Decode a compressed type description found at ptr in m. mode can be one of MONO_PARSE_MOD_TYPE, MONO_PARSE_PARAM, MONO_PARSE_RET, MONO_PARSE_FIELD, MONO_PARSE_LOCAL, MONO_PARSE_TYPE. This function can be used to decode type descriptions in method signatures, field signatures, locals signatures etc. To parse a generic type, `generic_container' points to the current class'es (the `generic_container' field in the MonoClass) or the current generic method's (stored in image->property_hash) generic container. When we encounter any MONO_TYPE_VAR or MONO_TYPE_MVAR's, they're looked up in this MonoGenericContainer. LOCKING: Acquires the loader lock.

Generics Support

mono_metadata_generic_class_is_valuetype

Prototype: mono_metadata_generic_class_is_valuetype

mono_metadata_inflate_generic_inst

Prototype: mono_metadata_inflate_generic_inst

mono_metadata_load_generic_params

Prototype: mono_metadata_load_generic_params

Tokens

mono_ldtoken

Prototype: mono_ldtoken

mono_ldstr

MonoString* mono_ldstr (MonoDomain *domain, MonoImage *image, guint32 idx)

Parameters

domain:
the domain where the string will be used.
image:
a metadata context
idx:
index into the user string table.

Returns

a loaded string from the image/idx combination.

Remarks

Implementation for the ldstr opcode.

mono_exception_from_token

MonoException* mono_exception_from_token (MonoImage *image, guint32 token)

Parameters

image:
the Mono image where to look for the class
token:
The type token of the class

Returns

the initialized exception instance.

Remarks

Creates an exception of the type given by token.

OpCodes

mono_opcode_name

Prototype: mono_opcode_name