Dynamic Plugin Quickstart - Revision history

MakoBot: Robot: Replacing 'OpenSim' to 'OpenSimulator', which is the precise name

2012-03-04T06:21:45Z

Robot: Replacing 'OpenSim' to 'OpenSimulator', which is the precise name

MakoBot: Robot: Cosmetic changes

2012-03-04T02:59:01Z

Robot: Cosmetic changes

MakoBot: Removed 'Template:' prefix from template includings and/or changed external-link into internal-link

2011-06-10T14:22:29Z

Removed 'Template:' prefix from template includings and/or changed external-link into internal-link

Justincc at 21:28, 6 May 2011

2011-05-06T21:28:18Z

Ideia Boa at 14:47, 21 May 2009

2009-05-21T14:47:16Z

Mikem at 02:06, 10 March 2009

2009-03-10T02:06:02Z

Mikem: /* Defining Extension Points */

2009-03-10T02:05:11Z

‎Defining Extension Points

Mikem: New page: A quick guide to writing plugins. Please refer to How to create a dynamic plugin for more in-depth information. === Defining Extension Points === Extension points describe the locati...

2009-03-10T02:02:21Z

New page: A quick guide to writing plugins. Please refer to How to create a dynamic plugin for more in-depth information. === Defining Extension Points === Extension points describe the locati...

New page

A quick guide to writing plugins. Please refer to [[How to create a dynamic plugin]] for more in-depth information.

=== Defining Extension Points ===

Extension points describe the location in the program where external modules can be plugged-in at runtime. Extension points can be defined in one of two ways:

* decorating interfaces, classes or methods with attributes in the source code
* embedding an XML file, called a manifest, as a resource in an assembly

In OpenSim, the preferred method is to embed an XML manifest in the assembly. Below is an example manifest defining one extension point in the AssetInventoryServer:

<source lang="xml"><Addin id="OpenSim.Grid.AssetInventoryServer" isroot="true" version="0.1">
<Runtime>
<Import assembly="OpenSim.Grid.AssetInventoryServer.exe" />
<Import assembly="OpenSim.Framework.dll" />
</Runtime>
<ExtensionPoint path="/OpenSim/AssetInventoryServer/AssetStorageProvider">
<ExtensionNode name="Plugin"
type="OpenSim.Framework.PluginExtensionNode"
objectType="OpenSim.Grid.AssetInventoryServer.IAssetStorageProvider" />
</ExtensionPoint>
</Addin></source>

This manifest contains the following elements:

* '''Addin'''
** '''id''': an identifier describing this addin, used for dependencies in other addins.
** '''isroot''': set to '''true''' if this manifest does not define any ''extension nodes'', otherwise can be left out completely.
** '''version''': a version number, also used for dependencies in other addins.
* '''Runtime''': a list of assemblies that need to be imported by Mono.Addins as it builds the plugin repository. In the example, the <code>OpenSim.Grid.AssetInventoryServer.exe</code> assembly contains the definition for <code>OpenSim.Grid.AssetInventoryServer.IAssetStorageProvider</code> interface, while <code>OpenSim.Framework.dll</code> contains a definition for <code>OpenSim.Framework.PluginExtensionNode</code>.
* '''ExtensionPoint'''
** '''path''': the location of the extension point in the extension point tree (see [http://www.mono-project.com/Introduction_to_Mono.Addins#Extension_Paths Extension Paths]).
* '''ExtensionNode'''
** '''name''': a name describing this extension node.
** '''type''': a class that handles plugin loading, this should probably be <code>OpenSim.Framework.PluginExtensionNode</code> unless you know what you're doing.
** '''objectType''': an instance of this object will be loaded into this extension point at runtime. This is probably what your plugin will instantiate/subclass/implement.

At this stage, all that is needed is <code>OpenSim.Grid.AssetInventoryServer.IAssetStorageProvider</code> defined and present in <code>OpenSim.Grid.AssetInventoryServer.exe</code>.

=== Defining Extensions ===

Extensions that implement extension points are defined in a similar way. Below is an example corresponding XML file describing a plugin for the above extension point:

<source lang="xml"><Addin id="OpenSim.Grid.AssetInventoryServer.Plugins.OpenSim" version="0.1">
<Runtime>
<Import assembly="OpenSim.Grid.AssetInventoryServer.Plugins.OpenSim.dll" />
<Import assembly="OpenSim.Data.dll" />
</Runtime>

<Dependencies>
<Addin id="OpenSim.Grid.AssetInventoryServer" version="0.1" />
</Dependencies>

<ExtensionPoint path = "/OpenSim/AssetData">
<ExtensionNode name="Plugin"
type="OpenSim.Framework.PluginExtensionNode"
objectType="OpenSim.Data.IAssetDataPlugin" />
</ExtensionPoint>

<Extension path="/OpenSim/AssetInventoryServer/AssetStorageProvider">
<Plugin id="OpenSimAssetStorage"
provider="OpenSim.Grid.AssetInventoryServer.Plugins.OpenSim.dll"
type="OpenSim.Grid.AssetInventoryServer.Plugins.OpenSim.OpenSimAssetStoragePlugin" />
</Extension>
</Addin></source>

The elements (not in the same order as in the file) are:

* '''Addin'''
** '''id''': a string identifying this plugin, can be used for dependencies in other plugins.
** '''version''': a version of this plugin, also used for dependencies in other plugins.
* '''Runtime''': a list of assemblies to import at runtime while Mono.Addins builds up the plugin registry. In this case, <code>OpenSim.Grid.AssetInventoryServer.Plugins.OpenSim.dll</code> contains the definition for <code>OpenSim.Grid.AssetInventoryServer.Plugins.OpenSim.OpenSimAssetStoragePlugin</code>, and <code>OpenSim.Framework.dll</code> contains a definition for <code>OpenSim.Framework.PluginExtensionNode</code>.
* '''Dependencies''': describes other addin(s) required to be loaded before this addin can be loaded. The '''id''' and '''version''' is used.
* '''Extension'''
** '''path''': the path along the extension point tree to the extension point which this extension implements.
** '''Plugin'''
*** '''id''': a string identifying this particular extension. Pretty much an arbitrary string.
*** '''provider''': another property of the extension, which can be an arbitrary string. In OpenSim, the convention seems to be to place the assembly name here which contains this plugin.
*** '''type''': the fully qualified class name to be instantiated which implements the extension. In the code, this class will inherit from/implement the class/interface specified in '''objectType''' attribute of the '''ExtensionPath'''.
* '''NOTE''': this XML file also defines another extension point, meaning that this plugin also takes another plugin. Note the '''isroot''' attribute in the topmost '''Addin''' element is omitted.

=== Source Code ===

The relevant code which ends up in <code>OpenSim.Grid.AssetInventoryServer.exe</code> and loads the AssetStorage plugin looks something like this:

<source lang="csharp">private IAssetStorageProvider LoadAssetStorageProvider(string addinPath)
{
PluginLoader<IAssetStorageProvider> loader = new PluginLoader<IAssetStorageProvider>();
loader.Add(addinPath);

try
{
loader.Load();
}
catch (PluginNotInitialisedException e)
{
// log the error, clean up, exit if needed, etc
}

return loader.Plugin;
}

// Then, from elsewhere in the code:
IAssetStorageProvider StorageProvider = LoadAssetStorageProvider("/OpenSim/AssetInventoryServer/AssetStorageProvider");</source>

The <code>PluginLoader</code> class lives in <code>OpenSim.Framework</code>; have a look through the code for more plugin loading options.

@@ Line 2: / Line 2: @@
 {{Quicklinks}}
-'''NOTE: This tutorial now refers to a very old OpenSim and so is only partially useful. See [[IRegionModule]] for something more up to date.'''
+'''NOTE: This tutorial now refers to a very old OpenSimulator and so is only partially useful. See [[IRegionModule]] for something more up to date.'''
 <br />
@@ Line 45: / Line 45: @@
 At this stage, all that is needed is <code>OpenSim.Grid.AssetInventoryServer.IAssetStorageProvider</code> defined and present in <code>OpenSim.Grid.AssetInventoryServer.exe</code>.
-'''PLEASE NOTE''': embedding XML manifests in .exe assemblies doesn't work. The .addin.xml file must reside in a directory that Mono.Addins will scan for plugins. Currently in OpenSim this is the current working directory (<code>bin/</code>). Ideally all applications would consist of an .exe assembly and a .dll assembly which contains the embedded XML manifest.
+'''PLEASE NOTE''': embedding XML manifests in .exe assemblies doesn't work. The .addin.xml file must reside in a directory that Mono.Addins will scan for plugins. Currently in OpenSimulator this is the current working directory (<code>bin/</code>). Ideally all applications would consist of an .exe assembly and a .dll assembly which contains the embedded XML manifest.
 == Defining Extensions ==

@@ Line 2: / Line 2: @@
 {{Quicklinks}}
-'''NOTE: This tutorial now refers to a very old OpenSim and so is only partially useful.  See [[IRegionModule]] for something more up to date.'''
+'''NOTE: This tutorial now refers to a very old OpenSim and so is only partially useful. See [[IRegionModule]] for something more up to date.'''
 <br />

@@ Line 1: / Line 1: @@
 __NOTOC__
-{{Template:Quicklinks}}
+{{Quicklinks}}
 '''NOTE: This tutorial now refers to a very old OpenSim and so is only partially useful.  See [[IRegionModule]] for something more up to date.'''

@@ Line 1: / Line 1: @@
 __NOTOC__
 {{Template:Quicklinks}}
 <br />

← Older revision		Revision as of 14:47, 21 May 2009
Line 1:		Line 1:
		+	__NOTOC__
		+	{{Template:Quicklinks}}
		+	<br />
		+
	A quick guide to writing plugins. Please refer to [[How to create a dynamic plugin]] for more in-depth information.		A quick guide to writing plugins. Please refer to [[How to create a dynamic plugin]] for more in-depth information.

@@ Line 1: / Line 1: @@
 A quick guide to writing plugins. Please refer to [[How to create a dynamic plugin]] for more in-depth information.
-=== Defining Extension Points ===
+== Defining Extension Points ==
 Extension points describe the location in the program where external modules can be plugged-in at runtime. Extension points can be defined in one of two ways:
@@ Line 40: / Line 40: @@
 '''PLEASE NOTE''': embedding XML manifests in .exe assemblies doesn't work. The .addin.xml file must reside in a directory that Mono.Addins will scan for plugins. Currently in OpenSim this is the current working directory (<code>bin/</code>). Ideally all applications would consist of an .exe assembly and a .dll assembly which contains the embedded XML manifest.
-=== Defining Extensions ===
+== Defining Extensions ==
 Extensions that implement extension points are defined in a similar way. Below is an example corresponding XML file describing a plugin for the above extension point:
@@ Line 82: / Line 82: @@
 * '''NOTE''': this XML file also defines another extension point, meaning that this plugin also takes another plugin. Note the '''isroot''' attribute in the topmost '''Addin''' element is omitted.
-=== Source Code ===
+== Source Code ==
 The relevant code which ends up in <code>OpenSim.Grid.AssetInventoryServer.exe</code> and loads the AssetStorage plugin looks something like this:

← Older revision		Revision as of 02:05, 10 March 2009
Line 37:		Line 37:

	At this stage, all that is needed is <code>OpenSim.Grid.AssetInventoryServer.IAssetStorageProvider</code> defined and present in <code>OpenSim.Grid.AssetInventoryServer.exe</code>.		At this stage, all that is needed is <code>OpenSim.Grid.AssetInventoryServer.IAssetStorageProvider</code> defined and present in <code>OpenSim.Grid.AssetInventoryServer.exe</code>.
		+
		+	'''PLEASE NOTE''': embedding XML manifests in .exe assemblies doesn't work. The .addin.xml file must reside in a directory that Mono.Addins will scan for plugins. Currently in OpenSim this is the current working directory (<code>bin/</code>). Ideally all applications would consist of an .exe assembly and a .dll assembly which contains the embedded XML manifest.

	=== Defining Extensions ===		=== Defining Extensions ===