November 13, 2008
Creating a customized Plugin Template
In its basic form, CRM 4.0 Plugin development is straightforward, however it has many monotonous elements. This walkthrough on writing Plugins illustrates many of the repetitive tasks that plugin development entails. Among them are:
- Creation of a new Class Library Project
- Renaming of the default class (class1.cs or class1.vb to Plugin name)
- Adding references to the Microsoft.Crm.Sdk & Microsoft.Crm.SdkTypeProxy libraries
- Aliasing those libraries
- Making the class inherit from the IPlugin interface
- Adding the methods for that interface (or letting VS do it for you)
Most of these items are pretty simple to do, but it is monontonous and you have to remember to do it each time. However most non-trivial plugins require some sort of configuration information. Because plugins are dynamic link libraries hosted by CRM (and typically stored in the database), you can't use Settings.config,app.config or web.config files like you would in most other projects. If you need this functinoality, you need to roll your own solution. Fortunately, when you register each step for your Plugin, the PluginRegistration tool gives you two sections, one for Unsecure configuration and one for Secure Configuration. But unless you write code to do something with this information, simply storing it will provide no benefit. (Mitch Milam has an excellent introduction to this). To take advantage of configuration infomration, you need to add a new constructor to your plugin and then write code to read the settings. You can just copy and paste his code if you'd like, but in all likelihood you'll probably want to write something specifically suited to your needs. Normally this would be something you'd just create in a library and attach as a reference to your project. However because of the plugin registration process, you'll typically want to work with as few dll's as possible (assemblies which reside in the Global Assembly Cache are an exception to this because you don't need to do anything special to use them).
Anyway, I found myself copying and pasting the same class over and over into each plugin I wrote and it was something that got old quickly. Additionally, when never developers come on board who aren't familiar with Plugin development, they will typically get stuck making the same mistakes you made when you first started writing plugins, something which can cost a lot of time and frustration.
The solution to all of this is to create a Visual Studio project template which takes care of most of this stuff for you. And the CRM Team was kind enough to create such a template for us. While it's quite helpful, there were a few things that I find myself doing regularly that weren't included. Thanks to Visual Studio Team System's ability to export templates, this was easily resolved.
I started a new project template that included the following additions:
- Added a set of instructions on the requirements needed for plugin development
- Added the .snk file we use for our plugins to the project and registered it with the project
- Added a PostBuild command to optionally start the PluginRegistration tool after Release builds
- Added an XML document to store the settings for a plugin
- Modified the constructor to examine the configuration information and make sure it complied with the format I was expecting.
- Created Properties to hold the XML documents if they were provided
- Added a class to read the Settings
- Added methods to handle nullable types
- Added an extension class to allow me to read configuration values from within the types themselves
- Added a class to decrypt encrypted settings
- Documented how each of these classes could be used and included code samples so that new developers could easily know what they need to do and how to do it.
Assume that you wanted to do something similar, customized to your organisation's needs.
- I would recommend starting with the template I mentioned above. If you want to do it from scratch though, create a new Class library project in your language of choice.
- Add a class (I used the PluginConfiguration class mentioned in the article above) called PluginConfiguration for instance, to handle reading the configuration values
- Add any additional methods you may want
- If you want to use Extension methods, add a static class (the class must be static for it to be used for Extension methods) to hold your extension methods and then add the methods to it
- Add an XML file to the project. The article above suggests a format for the XML which I found to be very easy to use.
- Add a couple of sample values to it so that you can just fill them in on your new plugin projects (these also serve as a visual cue for new developers to know how to store their own values).
- Add your company's strong name key to the project and register it (Right click Project then choose Properties -> Signing -> Sign the assembly -> Navigate to your .snk file or use the <new> option to create a new one.
- Add any post build events you may want to use.
- On the File menu, select Export Template.
- You have the option to just create an Item template, but in this case, select the Project Template option.
- Specify an icon in the Template Icon drop down if you want an icon associated with the template
- Specify a name for the Template in the Template Name textbox.
- Give it a description in the Description textbox.
- If you want to use it immediately, select the Automatically Import the Template into Visual Studio checkbox.
Once you have done this, test it by selecting File -> New -> Project and under the My Templates section, you should see your new template available as shown below: