Class AssemblyReader

Reads information about .NET assemblies without loading them into the current process

Inheritance

System.Object

AssemblyReader

Implements

System.IDisposable

Inherited Members

System.Object.ToString()

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

Namespace: CilTools.Metadata

Assembly: CilTools.Metadata.dll

Syntax

public sealed class AssemblyReader : IDisposable

Remarks

When the library needs to resolve metadata tokens from the external assembly, it will attempt to read it using AssemblyReader. The AssemblyReader acts as a cache that stores assembly instances so we don't need to load them multiple times.

This type implements the System.IDisposable interface. Calling Dispose() releases all loaded assemblies. It is required to call Dispose() when you no longer need the instance of the AssemblyReader; there's no finalizer.

Constructors

AssemblyReader()

Declaration

public AssemblyReader()

Properties

ResolutionDirectories

Gets the collection of additional resolution directories

Declaration

public IEnumerable<string> ResolutionDirectories { get; }

Property Value

Type	Description
System.Collections.Generic.IEnumerable<System.String>

ResolveExternalRefs

Gets or sets the value indicating that assembly reader should resolve external assembly references when loading types. The default value is true.

Declaration

public bool ResolveExternalRefs { get; set; }

Property Value

Type	Description
System.Boolean

Remarks

This property indicates that resolving external references is allowed, however, if some API is explicitly invoked with the NoResolve option, the resolution will not be performed.

RuntimeDirectory

Gets or sets the directory to search for framework assemblies.

Declaration

public string RuntimeDirectory { get; set; }

Property Value

Type	Description
System.String	The directory to search for framework assemblies. The default value is the current runtime directory.

Remarks

Settings this property ro null or empty string resets it to default value.

Methods

AddResolutionDirectory(String)

Adds the specified directory into the collection of additional resolution directories

Declaration

public void AddResolutionDirectory(string path)

Parameters

Type	Name	Description
System.String	path

Dispose()

Releases resources associated with the assembly reader instance

Declaration

public void Dispose()

Remarks

Calling Dispose releases all loaded assemblies. It is required to call Dispose when you no longer need the instance of the AssemblyReader; there's no finalizer.

Load(AssemblyName)

Loads the assembly identified by the System.Reflection.AssemblyName

Declaration

public Assembly Load(AssemblyName name)

Parameters

Type	Name	Description
System.Reflection.AssemblyName	name	The name of assembly to load

Returns

Type	Description
System.Reflection.Assembly	The assembly object or null if the assembly reader failed to read the requested assembly.

Remarks

If the assembly is read successfully, it is saved to cache. Eventual attempts to read assembly with the same name will fetch it from the cache instead of loading from file again.

Load(String)

Loads the assembly identified by assembly name string.

Declaration

public Assembly Load(string name)

Parameters

Type	Name	Description
System.String	name	The full name of the assembly to read

Returns

Type	Description
System.Reflection.Assembly	The assembly object or null if the assembly reader failed to read the requested assembly.

Remarks

If the assembly is read successfully, it is saved to cache. Eventual attempts to read assembly with the same name will fetch it from the cache instead of loading from file again.

The full assembly name, besides the simple name, can contain the assembly version, public key token and culture. See https://docs.microsoft.com/dotnet/api/system.reflection.assemblyname for more information about full assembly names.

Exceptions

Type	Condition
System.ArgumentNullException	Name is null
System.ArgumentException	Name is empty string

LoadFrom(String)

Loads the assembly identified by assembly file path

Declaration

public Assembly LoadFrom(string path)

Parameters

Type	Name	Description
System.String	path	The path to assembly PE file to load

Returns

Type	Description
System.Reflection.Assembly	The assembly object or null if the assembly reader failed to read the requested assembly.

Remarks

If the assembly is read successfully, it is saved to cache. Eventual attempts to read assembly with the same path will fetch it from the cache instead of loading from file again.

Exceptions

Type	Condition
System.ArgumentNullException	Path is null
System.ArgumentException	Path is empty string

LoadImage(MemoryImage)

Loads the assembly from the specified memory image

Declaration

public Assembly LoadImage(MemoryImage image)

Parameters

Type	Name	Description
MemoryImage	image	The memory image to load

Returns

Type	Description
System.Reflection.Assembly	The assembly object or null if the assembly reader failed to read the requested assembly.

Remarks

If the assembly is read successfully and the path is set for a memory image, the loaded assembly is saved to cache. Eventual attempts to read assembly with the same path will fetch it from the cache instead of loading it again. If the path is not set, each call to this method will load a new assembly instance, potentially leading to an unbounded growth of consumed memory.

The CilTools.Runtime.ClrAssemblyReader.GetMemoryImage method could be used to load a memory image from a process.

RemoveAllResolutionDirectories()

Removes all directories from the collection of additional resolution directories

Declaration

public void RemoveAllResolutionDirectories()

RemoveResolutionDirectory(String)

Removes the specified directory from the collection of additional resolution directories

Declaration

public void RemoveResolutionDirectory(string path)

Parameters

Type	Name	Description
System.String	path

Events

AssemblyResolve

Raised when the assembly reader needs to resolve an external assembly

Declaration

public event ResolveEventHandler AssemblyResolve

Event Type

Type	Description
System.ResolveEventHandler

Remarks

When the assembly reader needs to resolve an external assembly, it first looks for it in the current runtime directory (where the system assemblies are located). Then it looks into a additional resolution directories. If the assembly is not found there, the reader calls the AssemblyResolve event handler so you can customize how assemblies are resolved. The rules for handling this event are similar with the System.AppDomain.AssemblyResolve event in .NET Framework. See https://docs.microsoft.com/dotnet/standard/assembly/resolve-loads for more information.

Implements

System.IDisposable