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
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
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
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
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
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)