mono-api-assembly.html

## Assemblies

Code in .NET and Mono is distributed in assemblies, there are shipped typically in files with the extension .exe or .dll, and they are files that extend the Portable Executable file format to include the Common Intermediate Language metadata and portable code.

Assemblies are typically loaded either from a given file path, or using an Assembly Name to load them from the Global Assembly Cache.

The Mono Assembly API contains method for dealing with assembly names, loading assemblies, accessing assembly components, modules and some advanced features.

Assemblies contain one or more images, the actual vessels for your code. The Image API documents the functions that operate on `MonoImage *`.

### Synopsis

#include <metadata/assembly.h> typedef struct _MonoImage MonoImage; typedef struct _MonoAssembly MonoAssembly;

### Assembly Loading

`mono_assembly_close`
Syntax
void mono_assembly_close (MonoAssembly *assembly)

Parameters

assembly | the assembly to release.

Description

This method releases a reference to the assembly. The assembly is only released when all the outstanding references to it are released.
`mono_assembly_get_object`
Syntax
MonoReflectionAssembly* mono_assembly_get_object (MonoDomain *domain, MonoAssembly *assembly)

Parameters

domain | an app domain
assembly | an assembly

Return value
a `System.Reflection.Assembly` object representing the `MonoAssembly` assembly.
`mono_assembly_load`
Syntax
MonoAssembly* mono_assembly_load (MonoAssemblyName *aname, const char *basedir, MonoImageOpenStatus *status)

Parameters

aname | A MonoAssemblyName with the assembly name to load.
basedir | A directory to look up the assembly at.
status | a pointer to a MonoImageOpenStatus to return the status of the load operation

Return value
the assembly referenced by aname loaded or `NULL` on error. On error the value pointed by status is updated with an error code.
Description

Loads the assembly referenced by aname, if the value of basedir is not `NULL`, it attempts to load the assembly from that directory before probing the standard locations.

`mono_assembly_load_full`
Syntax
MonoAssembly* mono_assembly_load_full (MonoAssemblyName *aname, const char *basedir, MonoImageOpenStatus *status, gboolean refonly)

Parameters

aname | A MonoAssemblyName with the assembly name to load.
basedir | A directory to look up the assembly at.
status | a pointer to a MonoImageOpenStatus to return the status of the load operation
refonly | Whether this assembly is being opened in "reflection-only" mode.

Return value
the assembly referenced by aname loaded or `NULL` on error. On error the value pointed by status is updated with an error code.
Description

Loads the assembly referenced by aname, if the value of basedir is not `NULL`, it attempts to load the assembly from that directory before probing the standard locations.

If the assembly is being opened in reflection-only mode (refonly set to `TRUE`) then no assembly binding takes place.

`mono_assembly_loaded`
Syntax
MonoAssembly* mono_assembly_loaded (MonoAssemblyName *aname)

Parameters

aname | an assembly to look for.

Return value
`NULL` If the given aname assembly has not been loaded, or a pointer to a `MonoAssembly` that matches the `MonoAssemblyName` specified.
Description

This is used to determine if the specified assembly has been loaded

`mono_assembly_load_from`
Syntax
MonoAssembly* mono_assembly_load_from (MonoImage *image, const char *fname, MonoImageOpenStatus *status)

Parameters

image | Image to load the assembly from
fname | assembly name to associate with the assembly
status | return status code

Return value
A valid pointer to a `MonoAssembly*` on success and then status will be set to `MONO_IMAGE_OK`; or `NULL` on error.

If there is an error loading the assembly the status will indicate the reason with status being set to `MONO_IMAGE_INVALID` if the image did not contain an assembly reference table.

Description

If the provided image has an assembly reference, it will process the given image as an assembly with the given name.

Most likely you want to use the `api:mono_assembly_load_full` method instead.

This is equivalent to calling `api:mono_assembly_load_from_full` with the refonly parameter set to `FALSE`.
`mono_assembly_load_from_full`
Syntax
MonoAssembly* mono_assembly_load_from_full (MonoImage *image, const char*fname, MonoImageOpenStatus *status, gboolean refonly)

Parameters

image | Image to load the assembly from
fname | assembly name to associate with the assembly
status | returns the status condition
refonly | Whether this assembly is being opened in "reflection-only" mode.

Return value
A valid pointer to a `MonoAssembly*` on success and the status will be set to `MONO_IMAGE_OK`; or `NULL` on error.

If there is an error loading the assembly the status will indicate the reason with status being set to `MONO_IMAGE_INVALID` if the image did not contain an assembly reference table.
Description

If the provided image has an assembly reference, it will process the given image as an assembly with the given name.

Most likely you want to use the `api:mono_assembly_load_full` method instead.

`mono_assembly_load_with_partial_name`
Syntax
MonoAssembly* mono_assembly_load_with_partial_name (const char *name, MonoImageOpenStatus *status)

Parameters

name | an assembly name that is then parsed by `api:mono_assembly_name_parse`.
status | return status code

Return value
`NULL` on failure, or a pointer to a `MonoAssembly` on success.
Description

Loads a `MonoAssembly` from a name. The name is parsed using `api:mono_assembly_name_parse`, so it might contain a qualified type name, version, culture and token.

This will load the assembly from the file whose name is derived from the assembly name by appending the `.dll` extension.

The assembly is loaded from either one of the extra Global Assembly Caches specified by the extra GAC paths (specified by the `MONO_GAC_PREFIX` environment variable) or if that fails from the GAC.

`mono_assembly_open`
Syntax
MonoAssembly* mono_assembly_open (const char *filename, MonoImageOpenStatus *status)

Parameters

filename | Opens the assembly pointed out by this name
status | return status code

Return value
a pointer to the `MonoAssembly` if filename contains a valid assembly or `NULL` on error. Details about the error are stored in the status variable.
Description

This loads an assembly from the specified filename. The filename allows a local URL (starting with a `file://` prefix). If a file prefix is used, the filename is interpreted as a URL, and the filename is URL-decoded. Otherwise the file is treated as a local path.

First, an attempt is made to load the assembly from the bundled executable (for those deployments that have been done with the `mkbundle` tool or for scenarios where the assembly has been registered as an embedded assembly). If this is not the case, then the assembly is loaded from disk using `api:mono_image_open_full`.

If the pointed assembly does not live in the Global Assembly Cache, a shadow copy of the assembly is made.

`mono_assembly_open_full`
Syntax
MonoAssembly* mono_assembly_open_full (const char *filename, MonoImageOpenStatus *status, gboolean refonly)

Parameters

filename | the file to load
status | return status code
refonly | Whether this assembly is being opened in "reflection-only" mode.

Return value
`NULL` on error, with the status set to an error code, or a pointer to the assembly.
Description

This loads an assembly from the specified filename. The filename allows a local URL (starting with a `file://` prefix). If a file prefix is used, the filename is interpreted as a URL, and the filename is URL-decoded. Otherwise the file is treated as a local path.

First, an attempt is made to load the assembly from the bundled executable (for those deployments that have been done with the `mkbundle` tool or for scenarios where the assembly has been registered as an embedded assembly). If this is not the case, then the assembly is loaded from disk using `api:mono_image_open_full`.

If the pointed assembly does not live in the Global Assembly Cache, a shadow copy of the assembly is made.

If refonly is set to true, then the assembly is loaded purely for inspection with the `System.Reflection` API.

`mono_set_assemblies_path`
Syntax
void mono_set_assemblies_path (const char* path)

Parameters

path | list of paths that contain directories where Mono will look for assemblies

Description

Use this method to override the standard assembly lookup system and override any assemblies coming from the GAC. This is the method that supports the `MONO_PATH` variable.

Notice that `MONO_PATH` and this method are really a very bad idea as it prevents the GAC from working and it prevents the standard resolution mechanisms from working. Nonetheless, for some debugging situations and bootstrapping setups, this is useful to have.
`mono_set_rootdir`
Syntax
void mono_set_rootdir (void)

Description

Registers the root directory for the Mono runtime, for Linux and Solaris 10, this auto-detects the prefix where Mono was installed.

### Working with Assemblies

`mono_assembly_fill_assembly_name`
Syntax
gboolean mono_assembly_fill_assembly_name (MonoImage *image, MonoAssemblyName *aname)

Parameters

image | Image
aname | Name

Return value
`TRUE` if successful
`mono_assembly_foreach`
Syntax
void mono_assembly_foreach (GFunc func, gpointer user_data)

Parameters

func | function to invoke for each assembly loaded
user_data | data passed to the callback

Description

Invokes the provided func callback for each assembly loaded into the runtime. The first parameter passed to the callback is the `MonoAssembly*`, and the second parameter is the user_data.

This is done for all assemblies loaded in the runtime, not just those loaded in the current application domain.
`mono_assembly_get_image`
Syntax
MonoImage* mono_assembly_get_image (MonoAssembly *assembly)

Parameters

assembly | The assembly to retrieve the image from

Return value
the `MonoImage` associated with this assembly.
Description

`mono_assembly_get_main`
Syntax
MonoAssembly* mono_assembly_get_main (void)

Return value
the assembly for the application, the first assembly that is loaded by the VM
Description

`mono_assembly_get_name`
Syntax
MonoAssemblyName* mono_assembly_get_name (MonoAssembly *assembly)

Parameters

assembly | The assembly to retrieve the name from

Return value
the `MonoAssemblyName` associated with this assembly.
Description

The returned name's lifetime is the same as assembly's.

`mono_assembly_getrootdir`
Syntax
G_CONST_RETURN gchar * mono_assembly_getrootdir (void)

Return value
a string with the directory, this string should not be freed.
Description

Obtains the root directory used for looking up assemblies.

`mono_assembly_get_assemblyref`
Syntax
gboolean mono_assembly_get_assemblyref_checked (MonoImage *image, int index, MonoAssemblyName *aname, MonoError *error)

Parameters

image | pointer to the `MonoImage` to extract the information from.
index | index to the assembly reference in the image.
aname | pointer to a `MonoAssemblyName` that will hold the returned value.
error | set on error

Return value
`TRUE` on success, otherwise sets error and returns `FALSE`
Description

Fills out the aname with the assembly name of the index assembly reference in image.

`mono_assembly_loaded_full`
Syntax
MonoAssembly* mono_assembly_loaded_full (MonoAssemblyName *aname, gboolean refonly)

Parameters

aname | an assembly to look for.
refonly | Whether this assembly is being opened in "reflection-only" mode.

Return value
`NULL` If the given aname assembly has not been loaded, or a pointer to a `MonoAssembly` that matches the `MonoAssemblyName` specified.
Description

This is used to determine if the specified assembly has been loaded
`mono_assembly_load_reference`
Syntax
void mono_assembly_load_reference (MonoImage *image, int index)

`mono_assembly_load_references`
Deprecated: There is no reason to use this method anymore, it does nothing
Syntax
void mono_assembly_load_references (MonoImage *image, MonoImageOpenStatus *status)

Parameters

image |
status |

Description

This method is now a no-op, it does nothing other than setting the status to `MONO_IMAGE_OK`
`mono_assembly_load_module`
Syntax
MonoImage* mono_assembly_load_module (MonoAssembly *assembly, guint32 idx)

`mono_assembly_invoke_load_hook`
Syntax
void mono_assembly_invoke_load_hook (MonoAssembly *ass)

`mono_assembly_invoke_search_hook`
Syntax
MonoAssembly* mono_assembly_invoke_search_hook (MonoAssemblyName *aname)

`mono_assembly_set_main`
Syntax
void mono_assembly_set_main (MonoAssembly *assembly)

`mono_assembly_setrootdir`
Syntax
void mono_assembly_setrootdir (const char *root_dir)

Parameters

root_dir | The pathname of the root directory where we will locate assemblies

Description

This routine sets the internal default root directory for looking up assemblies.

This is used by Windows installations to compute dynamically the place where the Mono assemblies are located.

`mono_register_config_for_assembly`
Syntax
void mono_register_config_for_assembly (const char* assembly_name, const char* config_xml)

`mono_register_symfile_for_assembly`
Syntax
void mono_register_symfile_for_assembly (const char *assembly_name, const mono_byte *raw_contents, int size)

### Assembly Names

The MonoAssemblyName contains the full identity of an assembly (name, culture, public key, public key token, version and any other flags).

These unmanaged objects represent the System.Reflection.AssemblyName managed type.
`mono_assembly_name_new`
Syntax
MonoAssemblyName* mono_assembly_name_new (const char *name)

Parameters

name | name to parse

Return value
a newly allocated structure or `NULL` if there was any failure.
Description

Allocate a new `MonoAssemblyName` and fill its values from the passed name.

`mono_assembly_name_get_name`
Syntax
const char* mono_assembly_name_get_name (MonoAssemblyName *aname)

`mono_assembly_name_get_culture`
Syntax
const char* mono_assembly_name_get_culture (MonoAssemblyName *aname)

`mono_assembly_name_get_version`
Syntax
uint16_t mono_assembly_name_get_version (MonoAssemblyName *aname, uint16_t *minor, uint16_t *build, uint16_t *revision)

`mono_assembly_name_get_pubkeytoken`
Syntax
mono_byte* mono_assembly_name_get_pubkeytoken (MonoAssemblyName *aname)

`mono_assembly_name_free`
Syntax
void mono_assembly_name_free (MonoAssemblyName *aname)

Parameters

aname | assembly name to free

Description

Frees the provided assembly name object. (it does not frees the object itself, only the name members).
`mono_stringify_assembly_name`
Syntax
char* mono_stringify_assembly_name (MonoAssemblyName *aname)

Parameters

aname | the assembly name.

Return value
a newly allocated string with a string representation of the assembly name.
Description

Convert aname into its string format. The returned string is dynamically allocated and should be freed by the caller.

`mono_assembly_names_equal`
Syntax
gboolean mono_assembly_names_equal (MonoAssemblyName *l, MonoAssemblyName *r)

Parameters

l | first assembly
r | second assembly.

Return value
`TRUE` if both assembly names are equal.
Description

Compares two `MonoAssemblyName` instances and returns whether they are equal.

This compares the names, the cultures, the release version and their public tokens.

### Modules

An assembly is made up of one or more modules.
`mono_module_file_get_object`
Syntax
MonoReflectionModule* mono_module_file_get_object (MonoDomain *domain, MonoImage *image, int table_index)

`mono_module_get_object`
Syntax
MonoReflectionModule* mono_module_get_object (MonoDomain *domain, MonoImage *image)

### Advanced

`mono_install_assembly_load_hook`
Syntax
void mono_install_assembly_load_hook (MonoAssemblyLoadFunc func, gpointer user_data)

`mono_install_assembly_search_hook`
Syntax
void mono_install_assembly_search_hook (MonoAssemblySearchFunc func, gpointer user_data)

`mono_install_assembly_refonly_search_hook`
Syntax
void mono_install_assembly_refonly_search_hook (MonoAssemblySearchFunc func, gpointer user_data)

`mono_install_assembly_preload_hook`
Syntax
void mono_install_assembly_preload_hook (MonoAssemblyPreLoadFunc func, gpointer user_data)

`mono_install_assembly_refonly_preload_hook`
Syntax
void mono_install_assembly_refonly_preload_hook (MonoAssemblyPreLoadFunc func, gpointer user_data)

`mono_install_assembly_postload_search_hook`
Syntax
void mono_install_assembly_postload_search_hook (MonoAssemblySearchFunc func, gpointer user_data)