## 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
mono_assembly_get_object

`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 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.

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 Mono Assembly 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
mono_assembly_open_full

`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
mono_assembly_fill_assembly_name

`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
void mono_assembly_get_assemblyref (MonoImage *image, int index, MonoAssemblyName *aname)

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.

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
mono_assembly_load_reference

`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
mono_assembly_load_module

`mono_assembly_invoke_load_hook`
Syntax
mono_assembly_invoke_load_hook

`mono_assembly_invoke_search_hook`
Syntax
mono_assembly_invoke_search_hook

`mono_assembly_set_main`
Syntax
mono_assembly_set_main

`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
mono_register_config_for_assembly

`mono_register_symfile_for_assembly`
Syntax
mono_register_symfile_for_assembly

### 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
mono_assembly_name_get_name

`mono_assembly_name_get_culture`
Syntax
mono_assembly_name_get_culture

`mono_assembly_name_get_version`
Syntax
mono_assembly_name_get_version

`mono_assembly_name_get_pubkeytoken`
Syntax
mono_assembly_name_get_pubkeytoken

`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 MonoAssemblyNames 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
mono_module_file_get_object

`mono_module_get_object`
Syntax
mono_module_get_object

### Advanced

`mono_install_assembly_load_hook`
Syntax
mono_install_assembly_load_hook

`mono_install_assembly_search_hook`
Syntax
mono_install_assembly_search_hook

`mono_install_assembly_refonly_search_hook`
Syntax
mono_install_assembly_refonly_search_hook

`mono_install_assembly_preload_hook`
Syntax
mono_install_assembly_preload_hook

`mono_install_assembly_refonly_preload_hook`
Syntax
mono_install_assembly_refonly_preload_hook

`mono_install_assembly_postload_search_hook`
Syntax
mono_install_assembly_postload_search_hook