Interface IGorgonPlugInService

A service to create, cache and return GorgonPlugIn instances.

Namespace: Gorgon.PlugIns
Assembly: Gorgon.Core.dll
Syntax
public interface IGorgonPlugInService
Remarks

This service object is meant to instantiate, and cache instances of GorgonPlugIn objects contained within external assemblies loaded by an assembly cache of some kind. 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;

void LoadFunctionality()
{
	using (GorgonMefPlugInCache 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");  // You can also pass a wild card like (e.g. *.dll, *.exe, etc...)

		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()}");
}

Properties

| Edit this page View Source

LoadedPlugInCount

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

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

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

Declaration
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
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
void UnloadAll()

Extension Methods