Class GorgonMefPlugInService

A service to create, cache and return GorgonPlugIn instances by using the built in Microsoft Extensibility Framework as its provider.

Inheritance
object
GorgonMefPlugInService
Implements
Inherited Members
Namespace: Gorgon.PlugIns
Assembly: Gorgon.Core.dll
Syntax
public sealed class GorgonMefPlugInService : IGorgonPlugInService
Remarks

This service object is meant to instantiate, and cache instances of GorgonPlugIn objects contained within external assemblies loaded by the GorgonMefPlugInService. It also allows the user to unload plugin instances when necessary.

A plugin can be any class within an assembly that inherits from the GorgonPlugIn base object. When the service is created, it will retrieve a list of all known plugins types that exist in previously loaded plugin assemblies (this list can also be updated with the ScanPlugIns() method). PlugIns are not created until they are requested from the service via the GetPlugIn<T>(string) or GetPlugIns<T>(AssemblyName) methods. When these methods are called, they will instantiate the plugin type, and cache it for quick retrieval on subsequent calls to the methods.

tip

A plugin assembly may contain many or one plugin type, otherwise it is not considered when enumerating plugin types.

Defining your own plugin

While any class can be a plugin within an assembly, Gorgon uses the following strategy to define a plugin assembly.

In your host assembly (an application, DLL, etc...):

// This will go into your host assembly (e.g. an application, another DLL, etc...)
// This defines the functionality that you wish to override in your plugin assembly.
public abstract class FunctionalityBase
{
	public abstract int DoSomething();
}

// This too will go into the host assembly and be overridden in your plugin assembly.
public abstract class FunctionalityPlugIn
: GorgonPlugIn
{
public abstract FunctionalityBase GetNewFunctionality();


protected FunctionalityPlugIn(string description)
{
}



}

In your plugin assembly:

tip

Be sure to reference your host assembly in the plugin assembly project. 

// We put the namespace here because when loading the plugin in our example below, we need to give a fully qualified name for the type that we're loading.
namespace Fully.Qualified.Name
{
	// Typically Gorgon makes the extension classes internal, but they can have a public accessor if you wish.
	class ConcreteFunctionality
		: FunctionalityBase
	{
		public override int DoSomething()
		{
			return 42;
		}
	}

public class ConcreteFunctionalityPlugIn
	: FunctionalityPlugIn
{
	public override FunctionalityBase GetNewFunctionality()
	{
		return new ConcreteFunctionality();
	}

	public ConcreteFunctionalityPlugIn()
		: base("What is the answer to life, the universe, and blah blah blah?")
	{
	}
}



}
Examples

This example shows how to load a plugin and get its plugin instance. It will use the ConcreteFunctionalityPlugIn above:

// Our base functionality.
private FunctionalityBase _functionality;
private GorgonMefPlugInCache _assemblies;

void LoadFunctionality()
{
	assemblies = new GorgonMefPlugInCache();

	// For brevity, we've omitted checking to see if the assembly is valid and such.
	// In the real world, you should always determine whether the assembly can be loaded 
	// before calling the Load method.
	_assemblies.LoadPlugInAssemblies("Your\Directory\Here", "file search pattern");  // You can pass a wild card like *.dll, *.exe, etc..., or an absolute file name like "MyPlugin.dll".

	IGorgonPlugInService pluginService = new GorgonMefPlugInService(_assemblies);

	_functionality = pluginService.GetPlugIn<FunctionalityBase>("Fully.Qualified.Name.ConcreteFunctionalityPlugIn"); 
}

void Main()
{
	LoadFunctionality();

	Console.WriteLine($"The ultimate answer and stuff: {_functionality.DoSomething()}");

    _assemblies?.Dispose();
}

Constructors

| Edit this page View Source

GorgonMefPlugInService(GorgonMefPlugInCache)

Initializes a new instance of the GorgonMefPlugInService class.

Declaration
public GorgonMefPlugInService(GorgonMefPlugInCache mefCache)
Parameters
Type Name Description
GorgonMefPlugInCache mefCache

The cache of MEF plugin assemblies.
Exceptions
Type Condition
ArgumentNullException

Thrown when the mefCache parameter is null.

Properties

| Edit this page View Source

LoadedPlugInCount

Property to return the number of plugins that are currently loaded in this service.

Declaration
public int LoadedPlugInCount { get; }
Property Value
Type Description
int

Methods

| Edit this page View Source

GetPlugInNames(AssemblyName)

Function to retrieve a list of names for available plugins.

Declaration
public IReadOnlyList<string> GetPlugInNames(AssemblyName assemblyName = null)
Parameters
Type Name Description
AssemblyName assemblyName

[Optional] Name of the assembly containing the plugins.
Returns
Type Description
IReadOnlyList<string>

A list of names for the available plugins.
Remarks

This method will retrieve a list of fully qualified type names for plugins contained within the GorgonMefPlugInCache passed to this object. This list is not indicative of whether the type has been created or not.

The assemblyName parameter, when not null, will return only plugin names belonging to that assembly. If the assembly is not loaded, then an exception is thrown.

| Edit this page View Source

GetPlugIn<T>(string)

Function to retrieve a plugin by its fully qualified type name.

Declaration
public T GetPlugIn<T>(string pluginName) where T : GorgonPlugIn
Parameters
Type Name Description
string pluginName

Fully qualified type name of the plugin to find.
Returns
Type Description
T

The plugin, if found, or null if not.
Type Parameters
Name Description
T

The base type of the plugin. Must implement GorgonPlugIn.
Exceptions
Type Condition
ArgumentNullException

Thrown when the pluginName is null.
ArgumentEmptyException

Thrown when the pluginName is empty.
| Edit this page View Source

GetPlugIns<T>(AssemblyName)

Function to retrieve the list of plugins from a given assembly.

Declaration
public IReadOnlyList<T> GetPlugIns<T>(AssemblyName assemblyName = null) where T : GorgonPlugIn
Parameters
Type Name Description
AssemblyName assemblyName

[Optional] The name of the assembly associated with the plugins.
Returns
Type Description
IReadOnlyList<T>

A list of plugins from the assembly.
Type Parameters
Name Description
T

Type of plugin to retrieve. Must implement GorgonPlugIn.
Remarks

This will retrieve all the plugins from the plugin service of the type T. If the assemblyName parameter is not null, then, the only the assembly with that name will be scanned for the plugin type.

| Edit this page View Source

ScanPlugIns()

Function to scan for plugins in the loaded plugin assemblies that are cached in the GorgonMefPlugInCache passed to this object.

Declaration
public void ScanPlugIns()
Remarks

This method will unload any active plugins, and, if implemented, call the dispose method for any plugin.

| Edit this page View Source

Unload(string)

Function to unload a plugin by its name.

Declaration
public bool Unload(string name)
Parameters
Type Name Description
string name

Fully qualified type name of the plugin to remove.
Returns
Type Description
bool

true if the plugin was unloaded successfully, false if it did not exist in the collection, or failed to unload.
Exceptions
Type Condition
ArgumentNullException

The name parameter was null.
ArgumentException

The name parameter was an empty string.
| Edit this page View Source

UnloadAll()

Function to unload all the plugins.

Declaration
public void UnloadAll()

Implements

Extension Methods