The add in header

Home > Reference Manual > Description of Add ins and Add in Roots > The add in header

Every add-in and root has a header which specifies basic information about the extension model. This header can be specified in an XML manifest or using custom attributes.

The description of an add-in root looks similar to the description of an add-in. In fact, from the point of view of the add-in engine, add-ins and add-in roots are almost the same, so they use the same description model. The following sections describe in detail all information that can be included in an add-in or add-in root description. The term "add-in" is used generically in this chapter to refer to add-ins and add-in roots, unless specifically differenced.

Declaration using custom attributes

Assemblies can be marked as being add-ins or add-in roots using one of the following attributes:

• [Mono.Addins.Addin]: specifies that the assembly is an add-in.
• [Mono.Addins.AddinRoot]: specifies that the assembly is an add-in root.

The following properties can be specified in both attributes:

Property	Description
Id	The identifier of the add-in. It is mandatory for add-in roots and for add-ins that can be extended, optional for other add-ins. It can be specified in the attribute constructor.
Version	The version of the add-in. Like the id, it is mandatory for add-in roots and for add-ins that can be extended. It can be specified in the attribute constructor.
Namespace	Namespace of the add-in. The full ID of an add-in is composed by "Namespace.Id".
CompatVersion	Version of the add-in with which this add-in is backwards compatible (optional).
Name	Display name of the add-in.
Category	Category to which the add-in belongs to.
Url	Url of a web page with more information about the add-in.
EnabledByDefault	When set to 'false', the add-in won't be enabled until it is explicitly enabled by the user. The default is 'true'.
Flags	Possible flags are: CantUninstall (the add-in can't be uninstalled), CantDisable (the add-in can't be disabled), Hidden (the add-in won't be visible in management tools).

Other attributes can also be used to specify additional information about the add-in:

• [Mono.Addins.AddinName] (v0.6): name of the add-in. It can be specified multiple times for different locales.
• [Mono.Addins.AddinDescription] (v0.6): description of the add-in. It can be specified multiple times for different locales.
• [System.Reflection.AssemblyDescription]: description of the add-in.
• [System.Reflection.AssemblyCopyright]: copyright of the add-in.
• [Mono.Addins.AddinAuthor]: author of the add-in. It can be used multiple times to specify multiple authors.

Examples

Here is an example of an add-in declaration using attributes:

[assembly:AddinRoot ("Core", "1.0", Namespace="TextEditor")]
[assembly:AddinDescription ("This add-in root provides the core functionality of the text editor")]
[assembly:AddinDescription ("Aquesta arrel de complements proporciona la funcionalitat bàsica de l'editor de text", Locale="ca")]
[assembly:AddinAuthor ("Some Author")]
[assembly:AddinAuthor ("Some Other Author")]

Declaration of an add-in:

[assembly:Addin ("SomeAddin", "1.0", Namespace="TextEditor")]
[assembly:AssemblyDescription ("Provides some additional functionality to the editor")]
[assembly:AddinAuthor ("Some Author")]

Custom properties (v0.6)

In addition to the above attributes, the [Mono.Addins.AddinProperty] attribute can be used to specify arbitrary user defined property values, which can optionally be localized. For example:

[assembly:AddinProperty ("License","Some license text")]
[assembly:AddinProperty ("License", "ca", "Text de llicència")]

In this example, a new property "License" is defined with the value "Some license text". This property is also defined for the locale 'ca', and will have a different value for it.

Declaration using an XML manifest

In an XML manifest, header information is declared in the root Addin element:

<Addin namespace="TextEditor"
	id="Core" 
	version="1.0"
	compatVersion="0.9"
	name="Text Editor"
	description="An extensible text editor."
	author="Some author"
	category="Office"
	url="http://some/url"
	defaultEnabled="true"
	flags="CantUninstall,..."
	isroot="true">
	...
</Addin>

The following describes the attributes and elements shown above:

XML	Description
/Addin/@id	The identifier of the add-in. It is mandatory for add-in roots and for add-ins that can be extended, optional for other add-ins.
/Addin/@namespace	Namespace of the add-in. The full ID of an add-in is composed by "namespace.name".
/Addin/@version	The version of the add-in. Like the id, it is mandatory for add-in roots and for add-ins that can be extended.
/Addin/@compatVersion	Version of the add-in with which this add-in is backwards compatible (optional).
/Addin/@name	Display name of the add-in.
/Addin/@description	Description of the add-in.
/Addin/@author	Author of the add-in.
/Addin/@url	Url of a web page with more information about the add-in.
/Addin/@defaultEnabled	When set to 'false', the add-in won't be enabled until it is explicitly enabled by the user. The default is 'true'.
/Addin/@flags	Comma separated list of add-in flags. Possible flags are: CantUninstall: The add-in can't be uninstalled, CantDisable: The add-in can't be disabled, Hidden: The add-in won't be visible in management tools.
/Addin/@isroot	Must be ''true'' if the description belongs to an add-in root.

### The add-in Header element (v0.6)

Starting in Mono.Addins 0.6, all header information can also be specified as xml elements inside a Header element. Both ways of specifying header information are equivalent, although properties can only be localized when using the header element.

Custom add-in properties can be specified in the add-in header.

For example:

<Addin>

  <Header>
      <Id>Core</Id>
      <Namespace>TextEditor</Namespace>
      <Version>1.0</Version>
      <CompatVersion>1.0</CompatVersion>
      <DefaultEnabled>true</DefaultEnabled>
      <Flags>CantUninstall,...</Flags>
      <IsRoot>true</IsRoot>
      <Name>Text Editor</Name>
      <Name locale="ca">Editor de Text</Name>
      <Description>An extensible text editor</Description>
      <Description locale="ca">Un editor de text extensible</Description>
      <Author>Some author</Author>
      <Category>Office</Category>
      <Url>http://some/url</Url>
      <CustomProperty>value</CustomProperty>
      ...
  </Header>
  ...
</Addin>

The following table describes the elements shown above:

XML	Description
/Addin/Header/Id	The identifier of the add-in. It is mandatory for add-in roots and for add-ins that can be extended, optional for other add-ins.
/Addin/Header/Namespace	Namespace of the add-in. The full ID of an add-in is composed by "namespace.name".
/Addin/Header/Version	The version of the add-in. Like the id, it is mandatory for add-in roots and for add-ins that can be extended.
/Addin/Header/CompatVersion	Version of the add-in with which this add-in is backwards compatible (optional).
/Addin/Header/Name	Display name of the add-in. It can be specified multiple times for different locales.
/Addin/Header/Name/@locale	Locale of the name element. For example "en-US". The country code is optional.
/Addin/Header/Description	Description of the add-in. It can be specified multiple times for different locales.
/Addin/Header/Description/@locale	Locale of the name element. For example "en-US". The country code is optional.
/Addin/Header/Author	Author of the add-in.
/Addin/Header/Url	Url of a web page with more information about the add-in.
/Addin/Header/DefaultEnabled	When set to 'false', the add-in won't be enabled until it is explicitly enabled by the user. The default is 'true'.
/Addin/Header/Flags	Comma separated list of add-in flags. Possible flags are: CantUninstall: The add-in can't be uninstalled, CantDisable: The add-in can't be disabled, Hidden: The add-in won't be visible in management tools.
/Addin/Header/IsRoot	Must be ''true'' if the description belongs to an add-in root.
/Addin/Header/CustomProperty	Any user-defined property. CustomProperty can be any element name, and the value text can be any string.