MonoAddins Wiki Rss Feed

New Comment on "Extensions"

jackjoy — Fri, 08 Mar 2013 08:24:41 GMT

It seems that [Mono.Addins.ExtensionNode] attribute should be [Mono.Addins.Extension] attribute.

New Comment on "Architecture Overview"

yanweigps — Fri, 16 Mar 2012 08:36:30 GMT

It's so nice!

New Comment on "Data-only Extension Points"

slluis — Tue, 06 Dec 2011 21:31:59 GMT

Fixed. Thanks!

Updated Wiki: Data-only Extension Points

slluis — Tue, 06 Dec 2011 21:31:43 GMT

Data-only Extension Points

Extension data doesn't always need to be type metadata. Mono.Addins also supports data-only extension points. Applications are composed by code and by data. Type extensions points allow extending the code, data extension points allow extending data. For example, a word processor application could declare an extension point for registering document templates, or the main menu could be declared as an extensible data structure. Mono.Addins offers a common API and extension model for all kinds of extensions.

Extension data can be specified using custom attributes, but it is also possible to use XML as explained in following chapters. For now, we'll stick to custom attributes.

Declaring a Data-only Extension Point

Here is an example of how to declare a data extension point:

using System;
using Mono.Addins;

[assembly:ExtensionPoint ("/HelloWorld/WelcomeMessages", ExtensionAttributeType=typeof(WelcomeMessageAttribute))]

public class WelcomeMessageAttribute: Attribute
{
	public WelcomeMessageAttribute ([NodeAttribute ("Text")] string text)
	{
		Text = text;
	}

	[NodeAttribute]
	public string Text { get; set; }
}

The [ExtensionPoint] attribute can be used at assembly level to declare a data-only extension point. The first parameter of the attribute is the Path of the extension point. The path is like an identifier of the extension point. It starts with a slash and can contain several identifiers separated by slashes, like a file system path (although it is not bound to a real file system path, it is just an identifier).

The ExtensionAttributeType property can be used to specify the custom attribute to be used to declare the extensions. The specified custom attribute must follow the rules explained in the Type Extension Metadata section.

Declaring Data Extensions

An add-in extending the above extension point would look like this:

using System;
using Mono.Addins;

[assembly:Addin]
[assembly:AddinDependency ("HelloWorld", "1.0")]

[assembly:WelcomeMessage ("Some message")]
[assembly:WelcomeMessage ("Another message")]

The above example declares two extensions of the /HelloWorld/WelcomeMessages extension point.

Querying Data Extension Points

The main application can query the data extension point using AddinManager.GetExtensionNodes():

using System;
using Mono.Addins;

[assembly:AddinRoot ("HelloWorld", "1.0")]

class MainClass
{
	public static void Main ()
	{
		AddinManager.Initialize ();
		AddinManager.Registry.Update ();
		
		foreach (ExtensionNode<WelcomeMessageAttribute> node in AddinManager.GetExtensionNodes ("/HelloWorld/WelcomeMessages")) {
			Console.WriteLine ("Message: " + node.Data.Text);
		}
	}
}

When querying a data-only extension point bound to a custom extension attribute, the AddinManager.GetExtensionNodes() will return nodes of type ExtensionNode<T>, where T is the type of the custom extension attribute. This class has a Data property which contains the instance of the custom attribute with the extension data.

Next topic: Data Files and Resources

Updated Wiki: Data-only Extension Points

slluis — Tue, 06 Dec 2011 21:30:56 GMT

Data-only Extension Points

Declaring a Data-only Extension Point

Here is an example of how to declare a data extension point:

using System;
using Mono.Addins;

[assembly:ExtensionPoint ("/HelloWorld/WelcomeMessages", ExtensionAttributeType=typeof(WelcomeMessageAttribute))]

public class WelcomeMessageAttribute: Attribute
{
	public WelcomeMessageAttribute ([NodeAttribute ("Text")] string text)
	{
		Text = text;
	}

	[NodeAttribute]
	public string Text { get; set; }
}

Declaring Data Extensions

An add-in extending the above extension point would look like this:

using System;
using Mono.Addins;

[assembly:Addin]
[assembly:AddinDependency ("HelloWorld", "1.0")]

[assembly:WelcomeMessage ("Some message")]
[assembly:WelcomeMessage ("Another message")]

The above example declares two extensions of the /HelloWorld/WelcomeMessages extension point.

Querying Data Extension Points

The main application can query the data extension point using AddinManager.GetExtensionNodes():

using System;
using Mono.Addins;

[assembly:AddinRoot ("HelloWorld", "1.0")]

class MainClass
{
	public static void Main ()
	{
		AddinManager.Initialize ();
		AddinManager.Registry.Update ();
		
		foreach (ExtensionNode<CommandAttribute> node in AddinManager.GetExtensionNodes ("/HelloWorld/WelcomeMessages")) {
			Console.WriteLine ("Message: " + node.Data.Text);
		}
	}
}

New Comment on "Data-only Extension Points"

AleckAgakhan — Mon, 05 Dec 2011 23:24:36 GMT

Just some typoes: [assembly:ExtensionPoint ("/HelloWorld/WelcomeMessages", ExtensionAttributeType=typeof(MessageAttribute))] must be [assembly:ExtensionPoint ("/HelloWorld/WelcomeMessages", ExtensionAttributeType=typeof(WelcomeMessageAttribute))] foreach (ExtensionNode<CommandAttribute> node in AddinManager.GetExtensionNodes ("/HelloWorld/WelcomeMessages")) must be foreach (ExtensionNode<WelcomeMessageAttribute> node in AddinManager.GetExtensionNodes ("/HelloWorld/WelcomeMessages"))

New Comment on "Architecture Overview"

nelsonhf — Wed, 16 Mar 2011 15:32:42 GMT

The code in the first example (AddInRoot) is not consistent with the one in "Programming Guide" / "Extension Points and Extensions". Shouldn't the AddInRoot name be "HelloWorld" instead of "TextEditor"?

Updated Wiki: Projects using Mono.Addins

slluis — Wed, 09 Mar 2011 11:45:32 GMT

This is a list of projects and applications that are using Mono.Addins.

If you are using Mono.Addins and your project is not in the list, please add a comment to this page and I will add it.

Updated Wiki: Programming Guide

slluis — Tue, 22 Feb 2011 07:57:21 GMT

Programming Guide

This guide explains the basic concepts of Mono.Addins:

Updated Wiki: Creating and Managing Add-in Packages

slluis — Tue, 22 Feb 2011 07:56:12 GMT

Creating and Managing Add-in Packages

Mono.Addins follows the xcopy model for managing add-ins: to install an add-in, all that needs to be done is to copy it to the application's add-ins folder. However, applications may want to offer an user interface for managing add-ins, and even may need to provide an on-line repository from which users can browse and install add-ins. Mono.Addins provides an API and a command line tool which makes it easier to implement add-in management tools in applications.

The mautil command line tool

mautil is a generic command line tool which can be used to manage add-ins of any Mono.Addins based application. It has commands for listing, installing and uninstalling add-ins, registering on-line repositories, and downloading add-ins from those repositories.

For example, to list all add-ins installed for an application, the following command can be used:

> mautil -p /my/app -reg /my/app/reg list

The -p argument specifies the location of the application executable (the directory where the application .exe is located), and the -reg argument specifies the location of the add-in registry for the application (the path provided when calling AddinManager.Initialize).

Creating add-in packages

Add-ins may be composed by several files and assemblies, so in order to make it easier to share, download and install add-ins from on-line repositories add-ins must be packaged. An add-in package is basically a compressed archive (with .mpack extension) which contains all files of an add-in. Add-in packages can be created using the mautil command tool. For example:

> mautil pack SomeAddin.dll

This command will generate a file name SomeAddin.mpack which contains SomeAddin.dll and any other file imported by that add-in. This command can also be used to package add-ins based on manifests:

> mautil pack SomeAddin.addin

Notice that only the main add-in file (either the dll or the manifest) has to be specified. It is important to properly declare assembly and file imports so that those are included in the package.

Creating an add-in repository

An on-line repository of add-ins can be created with some simple steps:

Package and copy all add-ins you want to publish to a directory

Run the following command (where /the/directory is the directory that contains the add-in packages). This command will generate some index files:

> mautil rep-build /the/directory

Make all the files available in an http server

Installing add-ins from a repository

Before installing add-ins from a repository, the repository has to be registered. This can be done using the following command:

> mautil -p /my/app -reg /my/app/reg rep-add http://some.server/some/directory

Available add-ins can be listed using the 'list-av' command:

> mautil -p /my/app -reg /my/app/reg list-av

Once the repository is installed, add-ins can be installed using the 'install' command:

> mautil -p /my/app -reg /my/app/reg install SomeAddin,1.0

Implementing application-specific add-in management tools

Mono.Addins provides an add-in management API which can be easily integrated in applications:

The Mono.Addins.Setup.SetupService class (in the Mono.Addins.Setup assembly) provides methods for installing and uninstalling add-ins, with support for dependency resolution.
The Mono.Addins.Setup.RepositoryRegistry class (available through the SetupService.Repositories property) allows registering on-line repositories, and listing available add-ins and add-in updates.
The Mono.Addins.Setup.SetupTool class can be used to implement an application-specific command line tool for managing add-ins. This tool will behave like mautil, but it will not be necessary to provide the application and registry paths, and it can be customized to provide application specific commands.
The Mono.Addins.Gui assembly provides several classes which implement an add-in manager user interface for GTK# based applications.

Updated Wiki: Creating and Managing Add-in Packages

slluis — Tue, 22 Feb 2011 07:54:55 GMT

Creating and Managing Add-in Packages

The mautil command line tool

Creating add-in packages

Creating an add-in repository

An on-line repository of add-ins can be created with some simple steps:

Package and copy all add-ins you want to publish to a directory

Run the following command (where /the/directory is the directory that contains the add-in packages). This command will generate some index files:

> mautil rep-build /the/directory

Make all the files available in an http server

Installing add-ins from a repository

Implementing application-specific add-in management tools

Mono.Addins provides an add-in management API which can be easily integrated in applications:

The Mono.Addins.Setup.SetupService class (in the Mono.Addins.Setup assembly) provides methods for installing and uninstalling add-ins, with support for dependency resolution.
The Mono.Addins.Setup.RepositoryRegistry class (available in SetupService.Repositories) allows registering on-line repositories, and listing available add-ins and add-in updates.
The Mono.Addins.Setup.SetupTool class can be used to implement an application-specific command line tool for managing add-ins. This tool will behave like mautil, but it will not be necessary to provide the application and registry paths, and it can be customized to provide application specific commands.
The Mono.Addins.Gui assembly provides several classes which implement an add-in manager user interface for GTK# based applications.

Updated Wiki: Creating and Managing Add-in Packages

slluis — Tue, 22 Feb 2011 07:54:15 GMT

Creating and Managing Add-in Packages

The mautil command line tool

Creating add-in packages

Creating an add-in repository

An on-line repository of add-ins can be created with some simple steps:

Package and copy all add-ins you want to publish to a directory

Run the following command (where /the/directory is the directory that contains the add-in packages). This command will generate some index files:

> mautil rep-build /the/directory

Make all the files available in an http server

Installing add-ins from a repository

Implementing application-specific add-in management tools

Mono.Addins provides an add-in management API which can be easily integrated in applications:

The Mono.Addins.Setup.SetupService class (in the Mono.Addins.Setup assembly) provides methods for installing and uninstalling add-ins, with support for dependency resolution.
The Mono.Addins.Setup.RepositoryRegistry class (available in SetupService.Repositories) allows registering on-line repositories, and listing available add-ins and add-in updates.
The *Mono.Addins.Setup.SetupTool" class can be used to implement an application-specific command line tool for managing add-ins. This tool will behave like mautil, but it will not be necessary to provide the application and registry paths, and it can be customized to provide application specific commands.
The Mono.Addins.Gui assembly provides several classes which implement an add-in manager user interface for GTK# based applications.

Updated Wiki: Creating and Managing Add-in Packages

slluis — Mon, 21 Feb 2011 20:36:36 GMT

Creating and Managing Add-in Packages

The mautil command line tool

Creating add-in packages

Add-ins may be composed by several files and assemblies, so in order to make it easier to share, download and install add-ins from on-line repositories add-ins must be packaged. An add-in package is basically a compressed archive (with .mpack extension) which contains all files of an add-in. Add-in packages can be created using the mautil command tool. For example:

> mautil pack SomeAddin.dll

This command will generate a file name SomeAddin.mpack which contains SomeAddin.dll and any other file imported by that add-in. This command can also be used to package add-ins based on manifests:

> mautil pack SomeAddin.addin

Notice that only the main add-in file (either the dll or the manifest) have to be specified. It is important to properly declare assembly and file imports so that those are included in the package.

Creating an add-in repository

An on-line repository of add-ins can be created with some simple steps:

Package and copy all add-ins you want to publish to a directory

Run the following command (where /the/directory is the directory that contains the add-in packages (.mpack files). This command will generate some index files:

> mautil rep-build /the/directory

Make all the files available in an http server

Implementing application-specific add-in management tools

Mono.Addins provides an add-in management API which can be easily integrated in applications:

The Mono.Addins.Setup.SetupService class (in the Mono.Addins.Setup assembly) provides methods for installing and uninstalling add-ins, with support for dependency resolution.
The Mono.Addins.Setup.RepositoryRegistry class (available in SetupService.Repositories) allows registering on-line repositories, and listing available add-ins and add-in updates.
The *Mono.Addins.Setup.SetupTool" class can be used to implement an application-specific command line tool for managing add-ins. This tool will behave like mautil, but it will not be necessary to provide the application and registry paths, and it can be customized to provide application specific commands.
The Mono.Addins.Gui assembly provides several classes which implement an add-in manager user interface for GTK# based applications.

Updated Wiki: Creating and Managing Add-in Packages

slluis — Mon, 21 Feb 2011 20:36:15 GMT

The mautil command line tool

Creating add-in packages

Add-ins may be composed by several files and assemblies, so in order to make it easier to share, download and install add-ins from on-line repositories add-ins must be packaged. An add-in package is basically a compressed archive (with .mpack extension) which contains all files of an add-in. Add-in packages can be created using the mautil command tool. For example:

> mautil pack SomeAddin.dll

This command will generate a file name SomeAddin.mpack which contains SomeAddin.dll and any other file imported by that add-in. This command can also be used to package add-ins based on manifests:

> mautil pack SomeAddin.addin

Notice that only the main add-in file (either the dll or the manifest) have to be specified. It is important to properly declare assembly and file imports so that those are included in the package.

Creating an add-in repository

An on-line repository of add-ins can be created with some simple steps:

Package and copy all add-ins you want to publish to a directory

Run the following command (where /the/directory is the directory that contains the add-in packages (.mpack files). This command will generate some index files:

> mautil rep-build /the/directory

Make all the files available in an http server

Implementing application-specific add-in management tools

Mono.Addins provides an add-in management API which can be easily integrated in applications:

The Mono.Addins.Setup.SetupService class (in the Mono.Addins.Setup assembly) provides methods for installing and uninstalling add-ins, with support for dependency resolution.
The Mono.Addins.Setup.RepositoryRegistry class (available in SetupService.Repositories) allows registering on-line repositories, and listing available add-ins and add-in updates.
The *Mono.Addins.Setup.SetupTool" class can be used to implement an application-specific command line tool for managing add-ins. This tool will behave like mautil, but it will not be necessary to provide the application and registry paths, and it can be customized to provide application specific commands.
The Mono.Addins.Gui assembly provides several classes which implement an add-in manager user interface for GTK# based applications.

Updated Wiki: Custom Extension Node Types

slluis — Mon, 21 Feb 2011 19:27:15 GMT

Custom Extension Node Types

Every extension point has to declare the type of extension node that it accepts. Add-ins can register new extension nodes to that extension point. At run-time, extension nodes are represented by instances of the class Mono.Addins.ExtensionNode or instances of a subclass of it. Hosts can query extension points and get instances of ExtensionNode to extract whatever extension information is needed from them.

Mono.Addins provides the class TypeExtensionNode, a type of extension node which covers a very common extension scenario: the host defines an interface (or type), and the add-in has to implement it. At run-time TypeExtensionNode represents a type registered by an add-in, and a host can create instances out of it.

TypeExtensionNode may be enough for simple applications, but more complex applications will need to define new extension node types, so more complex extension information can be declared in extension points. Also, extension nodes don't always need to represent type implementations. In those cases, a host will need to implement custom extension node types.

Custom extension node implementation

Creating extension node types is very simple. Let's see one example:

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		[NodeAttribute]
		string resource;
		
		[NodeAttribute]
		string name;
		
		public string Name {
			get { return name != null ? name : Id; }
		}
		
		public virtual string GetContent ()
		{
			using (StreamReader sr = new StreamReader(Addin.GetResource (resource))) {
				return sr.ReadToEnd (); 
			}
		}
	}
}

This extension node type is used in the Text Editor example to register file templates. When creating a new file, the user can choose a file template, so the new file will include the content provided by the template.

This class does several interesing things:

It inherits from Mono.Addins.ExtensionNode. All extension node types must be a subclass of this type.
It declares a field named resource and marks it with the NodeAttribute custom attribute. When creating a node instance, all fields marked with this attribute will be initialized using attribute values taken from the node.
It implements a GetContent method which gets the content of a template using Addin.GetResource. The Addin property is declared in ExtensionNode and provides access to add-in resources and types.

This node type would be able to represent nodes registered in an extension like this:

<Addin ...>
	...
	<Extension path="/TextEditor/Templates">
		<FileTemplate name="README" resource="readme-template.txt" />
		<FileTemplate name="ChangeLog" resource="changelog-template.txt" />
	</Extension>
	...
</Addin>

When calling AddinManager.GetExtensionNodes(), the add-in engine will read all registered elements and will create the corresponding ExtensionNode subclass instance for each of them. It will also transfer attribute values to fields marked with [NodeAttribute].

Extension nodes are not just data containers, but they can also implement some logic. In this example the host application doesn't need to know where does a FileTemplateNode get the template content from. This logic is hidden in FileTemplateNode. FileTemplateNode happens to get the content from a resource, but it might allow getting it from other places in the future.

The [NodeAttribute] attribute can be applied to fields and properties. It has several properties which allow defining and documenting the behavior of the attribute:

Property	Description
Name	Name of the attribute, to be used when it is different from the name of the field or property
Required	When set to 'true' specifies that it is mandatory to specify a value for the attribute
Description	Description of the purpose of the attribute
Localizable	When set to 'true', the value of the field or property is expected to be a string id which will be localized by the add-in engine
ContentType	Allows specifying the type of the content of a string attribute. This is for documentation purposes only.

Extension node deserialization

The [NodeAttribute] custom attribute can be used to specify fields and properties that have to be initialized from node attributes. By default, a field is will get its value from an attribute with the same name, although it is possible to specify a different name by setting the NodeAttribute.Name property. NodeAttribute also has a Required property for specifying if an attribute is mandatory or not. So for example the ''resource'' filed might be declared like this:

public class FileTemplateNode: ExtensionNode
{
	...
	// Will match elements like <FileTemplate resource-name="blah" />
	// The true parameter specifies that the attribute is required
	[NodeAttribute ("resource-name", true)]
	string resource;
	...
}

ExtensionNode subclasses can also override the virtual method Read (NodeElement elem) to take control on the process of loading a ExtensionNode instance out of an extension node. If the Read method is overriden (and if it doesn't call the base class) [NodeAttribute] attributes will be ignored.

[NodeAttribute ("resource-name", true)]
public class FileTemplateNode: ExtensionNode
{
	...
	string resource;

	protected override void Read (NodeElement elem)
	{
		// This is equivalent to the previous example, but more
		// eficient since reflection is not involved here
		resource = elem.GetAttribute ("resource-name");
	}
	...
}

Notice the [NodeAttribute] attribute declaration applied to the class. When using custom deserialization, [NodeAttribute] can be applied to the class (or to a field) to declare the extension node attributes. This information however is only used for documentation purposes, and the add-in engine will not use it to do any kind of check. All checks must be done by the Read method override.

Getting add-in types, files and resources

As seen in the previous examples, the object returned by the ExtensionNode.Addin property can be used to get information from the add-in that created a node. It is a protected property, and it is intended to be used by ExtensionNode subclasses to get whatever content is needed. There are three methods which can be used to get such content:

GetResource (string name): returns a resource embedded in any of the assemblies included in the add-in.
GetType (string name): returns a type implemented in any of the assemblies included in the add-in, or in any of the add-ins on which this add-in depends.
GetFilePath (string name): Returns a path to a file which has been deployed together with the add-in.

Working with add-in files

It is possible to distribute files together with the add-in, and access those files from extension nodes. To distribute a file with an add-in, the file has to be declared in the Runtime section. For example, let's say we improve FileTemplateNode, so it can get the template not only from resources, but also from files distributed together with the add-in. An add-in declaration might look like this:

<Addin namespace="TextEditor" id="Xml">
	...
	<Runtime>
		<Import assembly="TextEditor.Xml.dll" />
		<Import file="someTemplate.xml" />
	</Runtime>
	...
	<Extension path="/TextEditor/Templates">
		...
		<FileTemplate name="SomeTemplate" fileName="someTemplate.xml" />
		...
	</Extension>
	...
</Addin>

The FileTemplateNode class would need to handle the new fileName attribute:

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		[NodeAttribute]
		string resource;
		
		[NodeAttribute]
		string fileName;
		
		[NodeAttribute]
		string name;
		
		public string Name {
			get { return name != null ? name : Id; }
		}
		
		public virtual string GetContent ()
		{
			StreamReader sr;
			if (resource != null)
				sr = new StreamReader (Addin.GetResource (resource));
			else if (fileName != null)
				// GetFilePath returns the full path to the add-in file
				sr = new StreamReader (Addin.GetFilePath (fileName));
			else
				return null;

			using (sr) {
				return sr.ReadToEnd (); 
			}
		}
	}
}

The private data directory

Every add-in has a private directory which can be used to store add-in specific files created at run time. This directory is created the first time that access to it is requested, and will be deleted when the add-in is uninstalled.

For example, let's say we want to support compressed file templates in FileTemplateNode. The GetContent method would need to uncompress the file before reading it, and it should be done only once. The implementation might look like this:

public virtual string GetContent ()
{
	StreamReader sr;
	if (resource != null) {
		sr = new StreamReader (Addin.GetResource (resource));
	}
	else if (fileName != null) {
		
		// Get the full path to the add-in file
		string filePath = Addin.GetFilePath (fileName);
		
		// If it is a gzipped file, it needs additional processing
		if (filePath.EndsWith (".gz")) {
			
			// The file will be unzipped in an add-in specific folder
			string unzippedFile = Path.Combine (Addin.PrivateDataPath, Path.GetFileNameWithoutExtension (filePath));
			
			// Unzip only once
			if (!File.Exists (unzippedFile))
				UnzipFileTo (filePath, unzippedFile);
			
			filePath = unzippedFile;
		}
		sr = new StreamReader (filePath);
	}
	else
		return null;
	using (sr) {
		return sr.ReadToEnd (); 
	}
}

Default node name and description

When an extension point does not provide a name for a node type, a default node name will be used. This default node name is the name of the class that implements it.

It is also possible to provide a custom default name, and also a description, to be used in those cases. This information can be provided using the [ExtensionNode] attribute:

[ExtensionNode ("FileTemplate", "A file template the user can choose when creating a new file")]
class FileTemplateNode: Mono.Addins.ExtensionNode
{
	...
}

Handling children

The property ExtensionNode.ChildNodes returns a list of children of a node. ExtensionNode implementations can query this list in order to build objects which are composed by several nodes.

For example, the TextEditor.SubmenuNode extension node, which represents an extensible submenu of the main menu, might be implemented like this:

public class SubmenuNode: MenuNode
{
	[NodeAttribute]
	string label;
	
	public override Gtk.MenuItem GetMenuItem ()
	{
		// Create the menu item
		Gtk.MenuItem it = new Gtk.MenuItem (label);
		Gtk.Menu submenu = new Gtk.Menu ();

		// Iterate through all children, and add a menu item for each of them
		foreach (MenuNode node in ChildNodes)
			submenu.Insert (node.GetMenuItem (), -1);
		it.Submenu = submenu;
		return it;
	}
}

// Abstract class to be subclassed by any kind of node that
// can generate a menu item.
public abstract class MenuNode: ExtensionNode
{
	public abstract Gtk.MenuItem GetMenuItem ();
}

The ChildNodes list may dynamically change while the application is running as a result of add-ins being enabled/disabled, or if the status of some conditions change. There are some overridable methods which are called when this happen: OnChildNodeAdded, OnChildNodeRemoved and a more generic OnChildrenChanged.

The [ExtensionNodeChild] attribute allows declaring the type of the child nodes of a node:

[ExtensionNode ("Menu")]
[ExtensionNodeChild (typeof(MenuItemNode))]
[ExtensionNodeChild (typeof(MenuSeparatorNode))]
[ExtensionNodeChild (typeof(SubmenuNode))]
public class SubmenuNode: MenuNode
{
	...
} 

[ExtensionNode ("MenuSeparator")]
public class MenuSeparatorNode: MenuNode
{
	...
}

[ExtensionNode ("MenuItem")]
public class MenuItemNode: MenuNode
{
	...
}

Notice that it is allowed to use recursive node type references.

Localizable extension nodes

Some extension node types may have attributes that need to be localizable. For example, the label of a menu item, or (in the text editor example) the name of a file template. Any text attribute can be made localizable by setting the Localizable property of NodeAttribute to ''true''. For example:

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		...
		
		[NodeAttribute (Localizable=true)]
		string name;
		
		public string Name {
			get {
				// 'name' will be already localized here
				return name != null ? name : Id; 
			}
		}

		...
	}
}

When an attribute is declared localizable like this, the add-in engine will use the add-in localizer bound to the extension node to get a translation of the string, and will assign the translated string to the field.

When using custom deserialization, the RuntimeAddin.Localizer property can be used to get the localizer bound to the add-in declaring the extension node. The following example would be equivalent to the previous one:

namespace TextEditor
{
	[NodeAttribute ("name", Localizable=true)]
	public class FileTemplateNode: ExtensionNode
	{
		...
		
		string name;
		
		protected override void Read (NodeElement elem)
		{
			name = Addin.Localizer.GetString (elem.GetAttribute ("name"));
		}

		...
	}
}

The [NodeAttribute] attribute declaration is used in this case only for documentation purposes.

See Localization of Add-ins for more information about creating localizable add-ins.

Controlling add-in loading

Mono.Addins supports lazy loading of add-ins. Add-ins are never explicitly loaded, but they are loaded only when resources or types from that add-in are required. It is important to take this behavior into account when designing extension nodes. Let's see for example the implementation of the an extension node for registering toolbar buttons:

namespace TextEditor
{
	public class ToolButtonNode: ExtensionNode
	{
		// Name of the icon
		[NodeAttribute]
		string icon;
		
		// Name of the class that implements the command
		// to run when clicking the button
		[NodeAttribute]
		string commandType;
		
		public Gtk.ToolItem GetToolItem ()
		{
			// Create the button and subscribe the clicked event
			Gtk.ToolButton but = new Gtk.ToolButton (icon);
			but.Clicked += OnClicked;
			return but;
		}
		
		void OnClicked (object s, EventArgs a)
		{
			// Run the command when clicking the button
			ICommand command = (ICommand) Addin.CreateInstance (commandType);
			command.Run ();
		}
	}
}

The commandType attribute will have the name of a type which is supposed to implement ICommand. When the button is clicked, the event handler creates an instance of the command and executes it. The call to Addin.CreateInstance () will force the loading of the add-in that registered that node, since CreateInstance needs to load the type of the command. However, this will only happen when the button is clicked. That is, it would be possible to create a complete toolbar out of add-in buttons without having to load the add-ins that define them.

An extension node may need to know when the add-in that defined it has been loaded or unloaded, since it may need to do some initialization or cleanup work. ExtensionNode has two virtual methods OnAddinLoaded and OnAddinUnloaded which can be used for this purpose.

Updated Wiki: Custom Extension Node Types

slluis — Mon, 21 Feb 2011 19:22:08 GMT

Custom Extension Node Types

Custom extension node implementation

Creating extension node types is very simple. Let's see one example:

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		[NodeAttribute]
		string resource;
		
		[NodeAttribute]
		string name;
		
		public string Name {
			get { return name != null ? name : Id; }
		}
		
		public virtual string GetContent ()
		{
			using (StreamReader sr = new StreamReader(Addin.GetResource (resource))) {
				return sr.ReadToEnd (); 
			}
		}
	}
}

It inherits from Mono.Addins.ExtensionNode. All extension node types must be a subclass of this type.
It declares a field named resource and marks it with the NodeAttribute custom attribute. When creating a node instance, all fields marked with this attribute will be initialized using attribute values taken from the node.
It implements a GetContent method which gets the content of a template using Addin.GetResource. The Addin property is declared in ExtensionNode and provides access to add-in resources and types.

This node type would be able to represent nodes registered in an extension like this:

<Addin ...>
	...
	<Extension path="/TextEditor/Templates">
		<FileTemplate name="README" resource="readme-template.txt" />
		<FileTemplate name="ChangeLog" resource="changelog-template.txt" />
	</Extension>
	...
</Addin>

Property	Description
Name	Name of the attribute, to be used when it is different from the name of the field or property
Required	When set to 'true' specifies that it is mandatory to specify a value for the attribute
Description	Description of the purpose of the attribute
Localizable	When set to 'true', the value of the field or property is expected to be a string id which will be localized by the add-in engine
ContentType	Allows specifying the type of the content of a string attribute. This is for documentation purposes only.

Extension node deserialization

The [NodeAttribute] custom attribute can be used to specify fields that have to be initialized from node attributes. By default, a field is will get its value from an attribute with the same name, although it is possible to specify a different name by setting the NodeAttribute.Name property. NodeAttribute also has a Required property for specifying if an attribute is mandatory or not. So for example the ''resource'' filed might be declared like this:

public class FileTemplateNode: ExtensionNode
{
	...
	// Will match elements like <FileTemplate resource-name="blah" />
	// The true parameter specifies that the attribute is required
	[NodeAttribute ("resource-name", true)]
	string resource;
	...
}

[NodeAttribute ("resource-name", true)]
public class FileTemplateNode: ExtensionNode
{
	...
	string resource;

	protected override void Read (NodeElement elem)
	{
		// This is equivalent to the previous example, but more
		// eficient since reflection is not involved here
		resource = elem.GetAttribute ("resource-name");
	}
	...
}

Getting add-in types, files and resources

GetResource (string name): returns a resource embedded in any of the assemblies included in the add-in.
GetType (string name): returns a type implemented in any of the assemblies included in the add-in, or in any of the add-ins on which this add-in depends.
GetFilePath (string name): Returns a path to a file which has been deployed together with the add-in.

Working with add-in files

<Addin namespace="TextEditor" id="Xml">
	...
	<Runtime>
		<Import assembly="TextEditor.Xml.dll" />
		<Import file="someTemplate.xml" />
	</Runtime>
	...
	<Extension path="/TextEditor/Templates">
		...
		<FileTemplate name="SomeTemplate" fileName="someTemplate.xml" />
		...
	</Extension>
	...
</Addin>

The FileTemplateNode class would need to handle the new fileName attribute:

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		[NodeAttribute]
		string resource;
		
		[NodeAttribute]
		string fileName;
		
		[NodeAttribute]
		string name;
		
		public string Name {
			get { return name != null ? name : Id; }
		}
		
		public virtual string GetContent ()
		{
			StreamReader sr;
			if (resource != null)
				sr = new StreamReader (Addin.GetResource (resource));
			else if (fileName != null)
				// GetFilePath returns the full path to the add-in file
				sr = new StreamReader (Addin.GetFilePath (fileName));
			else
				return null;

			using (sr) {
				return sr.ReadToEnd (); 
			}
		}
	}
}

The private data directory

public virtual string GetContent ()
{
	StreamReader sr;
	if (resource != null) {
		sr = new StreamReader (Addin.GetResource (resource));
	}
	else if (fileName != null) {
		
		// Get the full path to the add-in file
		string filePath = Addin.GetFilePath (fileName);
		
		// If it is a gzipped file, it needs additional processing
		if (filePath.EndsWith (".gz")) {
			
			// The file will be unzipped in an add-in specific folder
			string unzippedFile = Path.Combine (Addin.PrivateDataPath, Path.GetFileNameWithoutExtension (filePath));
			
			// Unzip only once
			if (!File.Exists (unzippedFile))
				UnzipFileTo (filePath, unzippedFile);
			
			filePath = unzippedFile;
		}
		sr = new StreamReader (filePath);
	}
	else
		return null;
	using (sr) {
		return sr.ReadToEnd (); 
	}
}

Default node name and description

[ExtensionNode ("FileTemplate", "A file template the user can choose when creating a new file")]
class FileTemplateNode: Mono.Addins.ExtensionNode
{
	...
}

Handling children

public class SubmenuNode: MenuNode
{
	[NodeAttribute]
	string label;
	
	public override Gtk.MenuItem GetMenuItem ()
	{
		// Create the menu item
		Gtk.MenuItem it = new Gtk.MenuItem (label);
		Gtk.Menu submenu = new Gtk.Menu ();

		// Iterate through all children, and add a menu item for each of them
		foreach (MenuNode node in ChildNodes)
			submenu.Insert (node.GetMenuItem (), -1);
		it.Submenu = submenu;
		return it;
	}
}

// Abstract class to be subclassed by any kind of node that
// can generate a menu item.
public abstract class MenuNode: ExtensionNode
{
	public abstract Gtk.MenuItem GetMenuItem ();
}

[ExtensionNode ("Menu")]
[ExtensionNodeChild (typeof(MenuItemNode))]
[ExtensionNodeChild (typeof(MenuSeparatorNode))]
[ExtensionNodeChild (typeof(SubmenuNode))]
public class SubmenuNode: MenuNode
{
	...
} 

[ExtensionNode ("MenuSeparator")]
public class MenuSeparatorNode: MenuNode
{
	...
}

[ExtensionNode ("MenuItem")]
public class MenuItemNode: MenuNode
{
	...
}

Notice that it is allowed to use recursive node type references.

Localizable extension nodes

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		...
		
		[NodeAttribute (Localizable=true)]
		string name;
		
		public string Name {
			get {
				// 'name' will be already localized here
				return name != null ? name : Id; 
			}
		}

		...
	}
}

namespace TextEditor
{
	[NodeAttribute ("name", Localizable=true)]
	public class FileTemplateNode: ExtensionNode
	{
		...
		
		string name;
		
		protected override void Read (NodeElement elem)
		{
			name = Addin.Localizer.GetString (elem.GetAttribute ("name"));
		}

		...
	}
}

The [NodeAttribute] attribute declaration is used in this case only for documentation purposes.

See Localization of Add-ins for more information about creating localizable add-ins.

Controlling add-in loading

namespace TextEditor
{
	public class ToolButtonNode: ExtensionNode
	{
		// Name of the icon
		[NodeAttribute]
		string icon;
		
		// Name of the class that implements the command
		// to run when clicking the button
		[NodeAttribute]
		string commandType;
		
		public Gtk.ToolItem GetToolItem ()
		{
			// Create the button and subscribe the clicked event
			Gtk.ToolButton but = new Gtk.ToolButton (icon);
			but.Clicked += OnClicked;
			return but;
		}
		
		void OnClicked (object s, EventArgs a)
		{
			// Run the command when clicking the button
			ICommand command = (ICommand) Addin.CreateInstance (commandType);
			command.Run ();
		}
	}
}

Updated Wiki: Custom Extension Node Types

slluis — Mon, 21 Feb 2011 19:04:04 GMT

Custom Extension Node Types

Custom extension node implementation

Creating extension node types is very simple. Let's see one example:

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		[NodeAttribute]
		string resource;
		
		[NodeAttribute]
		string name;
		
		public string Name {
			get { return name != null ? name : Id; }
		}
		
		public virtual string GetContent ()
		{
			using (StreamReader sr = new StreamReader(Addin.GetResource (resource))) {
				return sr.ReadToEnd (); 
			}
		}
	}
}

It inherits from Mono.Addins.ExtensionNode. All extension node types must be a subclass of this type.
It declares a field named resource and marks it with the NodeAttribute custom attribute. When creating a node instance, all fields marked with this attribute will be initialized using attribute values taken from the node.
It implements a GetContent method which gets the content of a template using Addin.GetResource. The Addin property is declared in ExtensionNode and provides access to add-in resources and types.

This node type would be able to represent nodes registered in an extension like this:

<Addin ...>
	...
	<Extension path="/TextEditor/Templates">
		<FileTemplate name="README" resource="readme-template.txt" />
		<FileTemplate name="ChangeLog" resource="changelog-template.txt" />
	</Extension>
	...
</Addin>

Extension node deserialization

public class FileTemplateNode: ExtensionNode
{
	...
	// Will match elements like <FileTemplate resource-name="blah" />
	// The true parameter specifies that the attribute is required
	[NodeAttribute ("resource-name", true)]
	string resource;
	...
}

[NodeAttribute ("resource-name", true)]
public class FileTemplateNode: ExtensionNode
{
	...
	string resource;

	protected override void Read (NodeElement elem)
	{
		// This is equivalent to the previous example, but more
		// eficient since reflection is not involved here
		resource = elem.GetAttribute ("resource-name");
	}
	...
}

Getting add-in types, files and resources

GetResource (string name): returns a resource embedded in any of the assemblies included in the add-in.
GetType (string name): returns a type implemented in any of the assemblies included in the add-in, or in any of the add-ins on which this add-in depends.
GetFilePath (string name): Returns a path to a file which has been deployed together with the add-in.

Working with add-in files

<Addin namespace="TextEditor" id="Xml">
	...
	<Runtime>
		<Import assembly="TextEditor.Xml.dll" />
		<Import file="someTemplate.xml" />
	</Runtime>
	...
	<Extension path="/TextEditor/Templates">
		...
		<FileTemplate name="SomeTemplate" fileName="someTemplate.xml" />
		...
	</Extension>
	...
</Addin>

The FileTemplateNode class would need to handle the new fileName attribute:

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		[NodeAttribute]
		string resource;
		
		[NodeAttribute]
		string fileName;
		
		[NodeAttribute]
		string name;
		
		public string Name {
			get { return name != null ? name : Id; }
		}
		
		public virtual string GetContent ()
		{
			StreamReader sr;
			if (resource != null)
				sr = new StreamReader (Addin.GetResource (resource));
			else if (fileName != null)
				// GetFilePath returns the full path to the add-in file
				sr = new StreamReader (Addin.GetFilePath (fileName));
			else
				return null;

			using (sr) {
				return sr.ReadToEnd (); 
			}
		}
	}
}

The private data directory

public virtual string GetContent ()
{
	StreamReader sr;
	if (resource != null) {
		sr = new StreamReader (Addin.GetResource (resource));
	}
	else if (fileName != null) {
		
		// Get the full path to the add-in file
		string filePath = Addin.GetFilePath (fileName);
		
		// If it is a gzipped file, it needs additional processing
		if (filePath.EndsWith (".gz")) {
			
			// The file will be unzipped in an add-in specific folder
			string unzippedFile = Path.Combine (Addin.PrivateDataPath, Path.GetFileNameWithoutExtension (filePath));
			
			// Unzip only once
			if (!File.Exists (unzippedFile))
				UnzipFileTo (filePath, unzippedFile);
			
			filePath = unzippedFile;
		}
		sr = new StreamReader (filePath);
	}
	else
		return null;
	using (sr) {
		return sr.ReadToEnd (); 
	}
}

Default node name and description

[ExtensionNode ("FileTemplate", "A file template the user can choose when creating a new file")]
class FileTemplateNode: Mono.Addins.ExtensionNode
{
	...
}

Handling children

public class SubmenuNode: MenuNode
{
	[NodeAttribute]
	string label;
	
	public override Gtk.MenuItem GetMenuItem ()
	{
		// Create the menu item
		Gtk.MenuItem it = new Gtk.MenuItem (label);
		Gtk.Menu submenu = new Gtk.Menu ();

		// Iterate through all children, and add a menu item for each of them
		foreach (MenuNode node in ChildNodes)
			submenu.Insert (node.GetMenuItem (), -1);
		it.Submenu = submenu;
		return it;
	}
}

// Abstract class to be subclassed by any kind of node that
// can generate a menu item.
public abstract class MenuNode: ExtensionNode
{
	public abstract Gtk.MenuItem GetMenuItem ();
}

[ExtensionNode ("Menu")]
[ExtensionNodeChild (typeof(MenuItemNode))]
[ExtensionNodeChild (typeof(MenuSeparatorNode))]
[ExtensionNodeChild (typeof(SubmenuNode))]
public class SubmenuNode: MenuNode
{
	...
} 

[ExtensionNode ("MenuSeparator")]
public class MenuSeparatorNode: MenuNode
{
	...
}

[ExtensionNode ("MenuItem")]
public class MenuItemNode: MenuNode
{
	...
}

Notice that it is allowed to use recursive node type references.

Localizable extension nodes

namespace TextEditor
{
	public class FileTemplateNode: ExtensionNode
	{
		...
		
		[NodeAttribute (Localizable=true)]
		string name;
		
		public string Name {
			get {
				// 'name' will be already localized here
				return name != null ? name : Id; 
			}
		}

		...
	}
}

namespace TextEditor
{
	[NodeAttribute ("name", Localizable=true)]
	public class FileTemplateNode: ExtensionNode
	{
		...
		
		string name;
		
		protected override void Read (NodeElement elem)
		{
			name = Addin.Localizer.GetString (elem.GetAttribute ("name"));
		}

		...
	}
}

The [NodeAttribute] attribute declaration is used in this case only for documentation purposes.

See Localization of Add-ins for more information about creating localizable add-ins.

Controlling add-in loading

namespace TextEditor
{
	public class ToolButtonNode: ExtensionNode
	{
		// Name of the icon
		[NodeAttribute]
		string icon;
		
		// Name of the class that implements the command
		// to run when clicking the button
		[NodeAttribute]
		string commandType;
		
		public Gtk.ToolItem GetToolItem ()
		{
			// Create the button and subscribe the clicked event
			Gtk.ToolButton but = new Gtk.ToolButton (icon);
			but.Clicked += OnClicked;
			return but;
		}
		
		void OnClicked (object s, EventArgs a)
		{
			// Run the command when clicking the button
			ICommand command = (ICommand) Addin.CreateInstance (commandType);
			command.Run ();
		}
	}
}

Updated Wiki: Handling Add-ins at Run-time

slluis — Mon, 21 Feb 2011 18:44:45 GMT

Handling Add-ins at Run-time

The Mono.Addins API provides several classes to be used by add-in hosts for handling add-ins at run-time. Most of the operations can be done with the class Mono.Addins.AddinManager, which provides methods for:

initializing the add-in engine,
getting nodes from extension points,
subscribing to extension events.

Initialization of the add-in manager

The first thing an add-in host has to do before using any of the Mono.Addins classes is to initialize the add-in engine using the AddinManager.Initialize() method. It's a very simple operation:

public class TextEditorApplication
{
	public static void Main ()
	{
		// Initialize the add-in engine
		AddinManager.Initialize (".");
	}
}

This method has several optional parameters which specify the location of the application add-ins and other settings:

Parameter	Description
configDir	Directory where the add-in engine configuration information will be stored. If the path is relative, it is assumed to be relative to the application path. If no value is provided, the global location /etc/mono.addins will be used.
addinsDir	Directory where to look for add-ins. If the path is relative, it is assumed to be relative to configDir. If not specified, the relative directory "addins" is used (that is, the directory will be configDir/addins
databaseDir	Directory where to create the add-in cache database. If the path is relative, it is assumed to be relative to configDir. If not specified, the configDir path is used.

See Add-in discovery for more information about how add-ins are found and loaded.

Querying Extension Points

The AddinManager class offers several methods for getting extensions from an extension point. The most basic method is GetExtensionNodes, which can be used like this:

foreach (ExtensionNode node in AddinManager.GetExtensionNodes ("/TextEditor/StartupCommands")) {
	Console.WriteLine ("Command: " + node.Id);
}

It is important to notice that getting the extensions of a node won't normally result in loading any add-in. The add-in engine is able to extract the needed information from add-ins without having to load them.

The nodes returned from GetExtensionNodes will have the actual node type, depending on the node name that was used by add-ins to register them. So, for the StartupCommands commands extension (described in the previous chapter) it would be safe to do:

foreach (TypeExtensionNode node in AddinManager.GetExtensionNodes ("/TextEditor/StartupCommands")) {
	ICommand command = (ICommand) node.CreateInstance ();
	command.Run ();
}

Querying Type-bound Extension Points

The AddinManager class provides the method GetExtensionObjects (with several overloads) for querying extension points which are bound to types (that is, whose extension nodes are of type TypeExtensionNode). This method works like GetExtensionNode, but instead of returning a node, it casts the node to TypeExtensionNode and returns the result of calling CreateInstance (or optionally GetInstance).

For example, the previous GetExtensionNodes call might be simplified like this:

foreach (ICommand cmd in AddinManager.GetExtensionObjects ("/TextEditor/StartupCommands"))
	cmd.Run ();

If the extension point was declared using the TypeExtensionPointAttribute, you can specify a type reference instead of an extension path:

foreach (ICommand cmd in AddinManager.GetExtensionObjects (typeof(ICommand)))
	cmd.Run ();

Extension Object Lifetime

When querying and extension point, Mono.Addins provides three different ways of managing the creation of extension objects:

Shared objects: objects are created only once and shared in all queries. This is the default mode.
Non-shared objects: a new object is created for every query.
Shared by context: like Shared Objects, but only within a specific context.

By default, GetExtensionObjects returns shared objects.. The first time an extension point is queried, the add-in engine creates an instance of the extension objects to be returned. Those instances are cached, so the next time the extension point is queried, the same set of objects is returned. The GetExtensionObjects method has an optional reuseInstances parameter which can be set to False to get a set of non-shared objects from the extension point. For example:

// This first loop will create instances of each type registered in the extension point
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// The second loop will reuse and return the same instances created in the previous loop
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// This loop will create new instances, since the 'reuseInstances' parameter is set to false
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (false))
	cmd.Run ();

Objects can also be shared by context. Mono.Addins allows creating different Extension Contexts out of the extension model. Each extension context manages the object lifetime independently. Objects which are shared in one context will not be shared with other contexts. A context can be created using the AddinManager.CreateExtensionContext () method. This method returns an ExtensionContext instance, which has methods for querying extension points, just like AddinManager. For example:

// Create two different contexts
ExtensionContext ctx1 = AddinManager.CreateExtensionContext ();
ExtensionContext ctx2 = AddinManager.CreateExtensionContext ();

(...)

// Every time this loop is executed, it will process the same set of instances
foreach (ICommand cmd in ctx1.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// Every time this loop is executed, it will process the same set of instances,
// but the instances are not the same as the ones returned for ctx1
foreach (ICommand cmd in ctx2.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

Extension Events

AddinManager offers several event sources to which add-in hosts can subscribe to be notified when an extension node is added or removed from an extension point. This may happen in two cases:

When an add-in is installed/uninstalled or enabled/disabled from inside a host application.
When there are extension nodes bound to conditions, and the status of those conditions change.

Using extension change events, it is possible to implement applications which can support dynamic activation and deactivation of add-ins at run-time.

There are two kind of extension change events:

AddinManager.ExtensionChanged event. This event is fired when any extension point in the add-in system changes. The event args object provides the path of the changed extension, although it does not provide information about what changed. Hosts subscribing to this event should get the new list of nodes using a query method such as AddinManager.GetExtensionNodes() and then update whatever needs to be updated.

AddinManager.AddExtensionNodeHandler (path, hanlder): hosts can call this method to be subscribed to an extension change event for a specific path. The event will be fired once for every individual node change. The event arguments include the change type (Add or Remove) and the extension node added or removed.

It is important to notice that when a host calls AddExtensionNodeHandler to register a handler, the handler will be called once for all nodes currently existing in the provided path. This behavior allows writing code like this:

class CommandManager
{
	// A list of commands
	ArrayList commands = new ArrayList ();

	public CommandManager ()
	{
		// Registers to node changes in the Commands path
		AddinManager.AddExtensionNodeHandler ("/TextEditor/Commands", OnExtensionChanged);
	}

	void OnExtensionChanged (object s, ExtensionNodeEventArgs args)
	{
		// Called when a node is added or removed
		ICommand command = (ICommand) args.ExtensionObject;
		if (args.Change == ExtensionChange.Add)
			commands.Add (command.Run ());
		else
			commands.Remove (command.Run ());
	}
}

In this example a CommandManager object subscribes to the extension change event for the path "/TextEditor/Commands". The idea is to keep all registered commands in a ''commands'' list. The class doesn't need to do any initialization of the commands list, because the call to AddExtensionNodeHandler will already fire an event of type ''Add'' for every existing node.

Updated Wiki: Handling Add-ins at Run-time

slluis — Mon, 21 Feb 2011 18:42:33 GMT

Handling Add-ins at Run-time

initializing the add-in engine,
getting nodes from extension points,
subscribing to extension events.

Initialization of the add-in manager

The first thing an add-in host has to do before using any of the Mono.Addins classes is to initialize the add-in engine using the AddinManager.Initialize() method. It's a very simple operation:

public class TextEditorApplication
{
	public static void Main ()
	{
		// Initialize the add-in engine
		AddinManager.Initialize (".");
	}
}

This method has several optional parameters which specify the location of the application add-ins and other settings:

Parameter	Description
configDir	Directory where the add-in engine configuration information will be stored. If the path is relative, it is assumed to be relative to the application path. If no value is provided, the global location /etc/mono.addins will be used.
addinsDir	Directory where to look for add-ins. If the path is relative, it is assumed to be relative to configDir. If not specified, the relative directory "addins" is used (that is, the directory will be configDir/addins
databaseDir	Directory where to create the add-in cache database. If the path is relative, it is assumed to be relative to configDir. If not specified, the configDir path is used.

Querying Extension Points

The AddinManager class offers several methods for getting extensions from an extension point. The most basic method is GetExtensionNodes, which can be used like this:

foreach (ExtensionNode node in AddinManager.GetExtensionNodes ("/TextEditor/StartupCommands")) {
	Console.WriteLine ("Command: " + node.Id);
}

foreach (TypeExtensionNode node in AddinManager.GetExtensionNodes ("/TextEditor/StartupCommands")) {
	ICommand command = (ICommand) node.CreateInstance ();
	command.Run ();
}

Querying Type-bound Extension Points

foreach (ICommand cmd in AddinManager.GetExtensionObjects ("/TextEditor/StartupCommands"))
	cmd.Run ();

If the extension point was declared using the TypeExtensionPointAttribute, you can specify a type reference instead of an extension path:

foreach (ICommand cmd in AddinManager.GetExtensionObjects (typeof(ICommand)))
	cmd.Run ();

Extension Object Lifetime

When querying and extension point, Mono.Addins provides three different ways of managing the creation of extension objects:

Shared objects: objects are created only once and shared in all queries. This is the default mode.
Non-shared objects: a new object is created for every query.
Shared by context: like Shared Objects, but only within a specific context.

// This first loop will create instances of each type registered in the extension point
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// The second loop will reuse and return the same instances created in the previous loop
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// This loop will create new instances, since the 'reuseInstances' parameter is set to false
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (false))
	cmd.Run ();

// Create two different contexts
ExtensionContext ctx1 = AddinManager.CreateExtensionContext ();
ExtensionContext ctx2 = AddinManager.CreateExtensionContext ();

(...)

// Every time this loop is executed, it will process the same set of instances
foreach (ICommand cmd in ctx1.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// Every time this loop is executed, it will process the same set of instances,
// but the instances are not the same as the ones returned for ctx1
foreach (ICommand cmd in ctx2.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

Extension Events

AddinManager offers several event sources to which add-in hosts can subscribe to be notified when an extension node is added or removed from an extension point. This may happen in two cases:

When an add-in is installed/uninstalled or enabled/disabled from inside a host application.
When there are extension nodes bound to conditions, and the status of those conditions change.

Using extension change events, it is possible to implement applications which can support dynamic activation and deactivation of add-ins at run-time.

There are two kind of extension change events:

AddinManager.ExtensionChanged event. This event is fired when any extension point in the add-in system changes. The event args object provides the path of the changed extension, although it does not provide information about what changed. Hosts subscribing to this event should get the new list of nodes using a query method such as AddinManager.GetExtensionNodes() and then update whatever needs to be updated.

AddinManager.AddExtensionNodeHandler (path, hanlder): hosts can call this method to be subscribed to an extension change event for a specific path. The event will be fired once for every individual node change. The event arguments include the change type (Add or Remove) and the extension node added or removed.

class CommandManager
{
	// A list of commands
	ArrayList commands = new ArrayList ();

	public CommandManager ()
	{
		// Registers to node changes in the Commands path
		AddinManager.AddExtensionNodeHandler ("/TextEditor/Commands", OnExtensionChanged);
	}

	void OnExtensionChanged (object s, ExtensionNodeEventArgs args)
	{
		// Called when a node is added or removed
		ICommand command = (ICommand) args.ExtensionObject;
		if (args.Change == ExtensionChange.Add)
			commands.Add (command.Run ());
		else
			commands.Remove (command.Run ());
	}
}

Updated Wiki: Handling Add-ins at Run-time

slluis — Mon, 21 Feb 2011 18:36:24 GMT

Handling Add-ins at Run-time

initializing the add-in engine,
getting nodes from extension points,
subscribing to extension events.

Initialization of the add-in manager

The first thing an add-in host has to do before using any of the Mono.Addins classes is to initialize the add-in engine using the AddinManager.Initialize() method. It's a very simple operation:

public class TextEditorApplication
{
	public static void Main ()
	{
		// Initialize the add-in engine
		AddinManager.Initialize (".");
	}
}

This method has several optional parameters which specify the location of the application add-ins and other settings:

Parameter	Description
configDir	Directory where the add-in engine configuration information will be stored. If no value is provided, the global location /etc/mono.addins will be used.
addinsDir	Directory where to look for add-ins. If the path is relative, it is assumed to be relative to configDir. If not specified, the relative directory "addins" is used (that is, the directory will be configDir/addins
databaseDir	Directory where to create the add-in cache database. If the path is relative, it is assumed to be relative to configDir. If not specified, the configDir path is used.

Querying Extension Points

The AddinManager class offers several methods for getting extensions from an extension point. The most basic method is GetExtensionNodes, which can be used like this:

foreach (ExtensionNode node in AddinManager.GetExtensionNodes ("/TextEditor/StartupCommands")) {
	Console.WriteLine ("Command: " + node.Id);
}

foreach (TypeExtensionNode node in AddinManager.GetExtensionNodes ("/TextEditor/StartupCommands")) {
	ICommand command = (ICommand) node.CreateInstance ();
	command.Run ();
}

Querying Type-bound Extension Points

foreach (ICommand cmd in AddinManager.GetExtensionObjects ("/TextEditor/StartupCommands"))
	cmd.Run ();

If the extension point was declared using the TypeExtensionPointAttribute, you can specify a type reference instead of an extension path:

foreach (ICommand cmd in AddinManager.GetExtensionObjects (typeof(ICommand)))
	cmd.Run ();

Extension Object Lifetime

When querying and extension point, Mono.Addins provides three different ways of managing the creation of extension objects:

Shared objects: objects are created only once and shared in all queries. This is the default mode.
Non-shared objects: a new object is created for every query.
Shared by context: like Shared Objects, but only within a specific context.

// This first loop will create instances of each type registered in the extension point
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// The second loop will reuse and return the same instances created in the previous loop
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// This loop will create new instances, since the 'reuseInstances' parameter is set to false
foreach (ICommand cmd in AddinManager.GetExtensionObjects<ICommand> (false))
	cmd.Run ();

// Create two different contexts
ExtensionContext ctx1 = AddinManager.CreateExtensionContext ();
ExtensionContext ctx2 = AddinManager.CreateExtensionContext ();

(...)

// Every time this loop is executed, it will process the same set of instances
foreach (ICommand cmd in ctx1.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

// Every time this loop is executed, it will process the same set of instances,
// but the instances are not the same as the ones returned for ctx1
foreach (ICommand cmd in ctx2.GetExtensionObjects<ICommand> (true))
	cmd.Run ();

Extension Events

AddinManager offers several event sources to which add-in hosts can subscribe to be notified when an extension node is added or removed from an extension point. This may happen in two cases:

When an add-in is installed/uninstalled or enabled/disabled from inside a host application.
When there are extension nodes bound to conditions, and the status of those conditions change.

Using extension change events, it is possible to implement applications which can support dynamic activation and deactivation of add-ins at run-time.

There are two kind of extension change events:

AddinManager.ExtensionChanged event. This event is fired when any extension point in the add-in system changes. The event args object provides the path of the changed extension, although it does not provide information about what changed. Hosts subscribing to this event should get the new list of nodes using a query method such as AddinManager.GetExtensionNodes() and then update whatever needs to be updated.

AddinManager.AddExtensionNodeHandler (path, hanlder): hosts can call this method to be subscribed to an extension change event for a specific path. The event will be fired once for every individual node change. The event arguments include the change type (Add or Remove) and the extension node added or removed.

class CommandManager
{
	// A list of commands
	ArrayList commands = new ArrayList ();

	public CommandManager ()
	{
		// Registers to node changes in the Commands path
		AddinManager.AddExtensionNodeHandler ("/TextEditor/Commands", OnExtensionChanged);
	}

	void OnExtensionChanged (object s, ExtensionNodeEventArgs args)
	{
		// Called when a node is added or removed
		ICommand command = (ICommand) args.ExtensionObject;
		if (args.Change == ExtensionChange.Add)
			commands.Add (command.Run ());
		else
			commands.Remove (command.Run ());
	}
}