Migrate your plugin to be compatible with July release

With July release of XrmToolBox, the way plugins are loaded changed to use MEF (Microsoft Extensibility Framework). This ensure that loading mechanism are handled automatically without any custom code.

If you developed plugins for previous versions of XrmToolBox, they won't work with July release. To update your plugins, follow the procedure below

Manage references

Add references to the following assemblies:

• System.ComponentModel.Composition: This is the MEF part
• XrmToolBox.Extensibility : This is a new assembly that gather all code that allows plugin development. This assembly is shipped with each new XrmToolBox release (from July 2015). Before this release is available, please download latest source code from XrmToolBox DEV branch to compile your own XrmToolBox.Extensibility assembly

Remove reference to the following assembly:

• XrmToolBox : There shouldn't be any need to reference this assembly anymore since all extensibility logic is contained in XrmToolBox.Extensibility assembly

Rename existing components

Using MEF, XrmToolBox plugins development requires an additional class that should use existing naming. To avoid confusion, it was necessary to rename some classes and interfaces.

If you are using PluginBase as the base class for your plugins, then this class is now named PluginControlBase. Rename the usage of this base class in your plugins.

Before:

public partial class ScriptsFinder : PluginBase
{
	// Your code
}

After:

public partial class ScriptsFinder : PluginControlBase
{
	// Your code
}

If you are implementing IMsCrmToolsPluginUserControl directly in your plugin code, then you have to use the interface renamed to IXrmToolBoxPluginControl

Before:

public partial class MyPlugin : UserControl, IMsCrmToolsPluginUserControl
{
	// Your code
} 

After:

public partial class MyPlugin : UserControl, IXrmToolBoxPluginControl
{
	// Your code
} 

Add a new class to describe your plugin

A new class that inherits from a new base class (named PluginBase, which implements interface IXrmToolBoxPlugin) has to be created. This class describes the plugin with metadata (see next chapter) and implements a method to return the UserControl which implements IXrmToolBoxPluginControl

using System.ComponentModel.Composition;
using XrmToolBox.Extensibility;
using XrmToolBox.Extensibility.Interfaces;

namespace MsCrmTools.SampleTool
{
	public class Plugin : PluginBase
    {
        public override IXrmToolBoxPluginControl GetControl()
        {
            return new SampleTool();
        }
    }
}

So, for each plugin you develop, you should have two classes : One that describe the plugin (which inherits form PluginBase) and one that is the UserControl to display your plugin (which inherits from PluginControlBase)

Add plugin metadata

The plugin class must be decorated with Export attribute to ensure discoverability of the plugin by XrmToolBox application. This attribute contains metadata that have to be specified:

• Name : The name of the tool that appears on the plugins list in XrmToolBox

• Description : The description of the tool that appears on the plugins list in XrmToolBox

• SmallImageBase64 : The base64 content of a 32x32 image to be used to display the plugin logo in the plugins list in XrmToolBox. If you specify null, a "No logo" logo is used.

• BigImageBase64 : The base64 content of a 80x80 image to be used to display the plugin logo in the plugins list in XrmToolBox. If you specify null, a "No logo" logo is used.

• BackgroundColor : The background color to display for the plugin in the plugins list in XrmToolBox. Can be a HTML color name or an hexadecimal code for the color.

• PrimaryFontColor : The color used to display the name of the plugin in the plugins list in XrmToolBox. Can be a HTML color name or an hexadecimal code for the color.

• SecondaryFontColor : The color used to display the name of the plugin author (in small icons display mode) in the plugins list in XrmToolBox. Can be a HTML color name or an hexadecimal code for the color.

Add the following Export attribute declaration to your plugin class:

 [Export(typeof(IXrmToolBoxPlugin)),
    ExportMetadata("Name", "The name of your tool"),
    ExportMetadata("Description", "The description of your tool"),
    ExportMetadata("SmallImageBase64", null), // null for "no logo" image or base64 image content 
    ExportMetadata("BigImageBase64", null), // null for "no logo" image or base64 image content 
    ExportMetadata("BackgroundColor", "Lavender"), // Use a HTML color name
    ExportMetadata("PrimaryFontColor", "#000000"), // Or an hexadecimal code
    ExportMetadata("SecondaryFontColor", "DarkGray")]
    public partial class SampleTool : PluginBase
    {
		// Your code here
	}

In addition, remove assembly attributes that described your plugin before:

[assembly: BackgroundColor("")]
[assembly: PrimaryFontColor("")]
[assembly: SecondaryFontColor("Gray")]
[assembly: SmallImageBase64(null)]
[assembly: BigImageBase64(null)]
public partial class SampleTool : PluginBase
{
	// Your code here
}

Adjust "Using" items to remove those which referenced XrmToolBox and add XrmToolBox.Extensibility "Using" required

You should be done!

Additional considerations

AssemblyInfo.cs file in your project was used before to reference plugin name, plugin description, company and version. Plugin name and plugin description are not used anymore so you can put here whatever your want. Company et Version are still used.