Friday, February 13, 2009

How to Create a Plugin for CRM 4.0

Plugins

Overview

Purpose of Plugins

The purpose of plugins is to add extended functionality to Microsoft Dynamics CRM. Plugins themselves can be thought of as company workflow. Plugins are triggered by the user or by system events and are programmed to perform functions on data within Microsoft CRM.

Purpose of this Documentation:

This document will provide my successor with information about the process used to create plugins and useful information about every plugin that I have created.

I will provide information about where each plugin is stored and the knowledge required to develop, register, and troubleshoot plugins in general.

Some of my sample code can be found on my blog. Customcrmsdk.blogspot.com

I will also describe in detail each plugin I have written. This information will include:



· Registration Information

· A general workflow and description

· Entities and attributes that are affected

· Entities and attributes that are referenced



Tools Required

To successfully create, register, and troubleshoot plugins you will need the following tools:

· Microsoft Visual Studio 2005 or 2008

o Make sure to update your .Net Framework to include all versions up to 3.0

· The Microsoft CRM SDK - Make sure it is the current version

· The Plugin Registration Tool

o I recommend downloading the source code and compiling it yourself

· CRM 4 Diagnostic Tool - It is a must have

· My Plugin Helper class





Basic Creation Process

Create a Simple Template

· Open up Visual Studio 2005 and select File > New > Project and select Visual C# on the left and Class Library on the right. Then give your project a name.


·
  • Then Click OK.
  • Next you need to add the microsoft.crm.sdk.dll and microsoft.crm.sdktypeproxy.dll files to the project folder.

o Do this by going to the SDK folder you downloaded earlier and navigate to the bin folder. Both files should be there. Simply copy and paste them into your project directory.

  • Then to add the reference to the project right click your solution name in the Solution Explorer and click Add Reference. Then click the Browse tab and navigate inside your project folder to find the two dll’s you added previously.
  • Then you need to add 2 more references. This time stay in the .NET Tab and add the references
    • System.Web.Services
    • System.EnterpriseService
  • Now you are ready to write your plugin class
  • Make sure that your class is using the following:

using System;

using System.Collections.Generic;

using System.Text;

using Microsoft.Crm.Sdk;

using Microsoft.Crm.SdkTypeProxy;

using Microsoft.Crm.Sdk.Query;

· The class declaration must look like this:

o public class Class1 : IPlugin

· The main method of the class must be:

o public void Execute(IPluginExecutionContext context)

o Everything you do is inside this method

· The first thing you should do is to create your ICrmService

o ICrmService service = (ICrmService)context.CreateCrmService(false);

o This is what you will use to make calls to the server

· Here is a template for all plugins.

using System;

using System.Collections.Generic;

using System.Text;

using Microsoft.Crm.Sdk;

using Microsoft.Crm.SdkTypeProxy;

using Microsoft.Crm.Sdk.Query;

namespace SamplePlugin

{

public class Class1 : IPlugin

{

public void Execute(IPluginExecutionContext context)

{

ICrmService service = (ICrmService)context.CreateCrmService(false);

}

}

}



Signing Your Plugin

This step is required. If you don’t sign the plugin nothing will work. I have made this mistake many times.

· Right click on the project name in the Solutions Explorer and click Properties

· Click the Signing tab, Checkmark “Sign the assembly” and click .


·

· Next, give your Key File a name and uncheck the “Protect my key file with a password”, and click OK.

·

Simple Troubleshooting

These steps are vital when creating a plugin. If any of these steps are not completed the Plugin Registration Tool will not recognize the .dll as a plugin.

· Did you add the microsoft.crm.sdk.dll and microsoft.crm.sdktypeproxy.dll?

· Did you modify the class declaration by adding : IPlugin?

· Did you sign the project?



Registering Plugins

Overview

The registration process is probably the most important step in the plugin development process. There are a couple questions you should ask yourself about the plugin regarding its operation.

· When do I want the plugin to fire?

· What entity will effectively trigger the plugin event?

· In which pipeline will the message be caught

· Is this a pre-event or post-event?

I will discuss these things in the following section. For now you need to make sure you have the Plugin Registration Tool configured and built. There are instructions inside the downloaded zip folder containing the tool. When you connect to the Microsoft CRM server for the first time with the plugin registration tool, the only information you will need to fill in is: The Label, Discovery Server, and Port. The other information should appear automatically when you connect.

Registering a Plugin

Now that you have configured and connected to your Microsoft CRM server with the Plugin Registration Tool you need to register a New Plugin followed by a New Step. I will guide you through the process step by step.

· After you have written your plugin or “assembly”, you need to build it. This will create a .dll file that you will use to register it.

· Make sure to save your assemblies in the \Server\bin\assembly directory on the Microsoft CRM server.

· Click the Register button then click Register New Assembly.

· At the top of the registration page you will see the browse button. Click on it and locate the \Server\bin\assembly directory and open your assembly that you relocated there earlier.

· Click Register Selected Plugins

· Click the Register button on the main window again and this time select Register New Step


·

· The first thing you should always check for is that the Plugin field contains the correct plugin. This is a common mistake.

· Next enter the name of the Primary Entity that is going to cause the plugin to run.

· Then enter the message.

o If the message you want doesn’t fill itself out after a couple letters then that message is not available for the entity you have selected.

· Choose the Filtering Attributes

o Ex. If you only want the plugin to fire if the price field of a Product is updated

· Choose the stage of Execution

o Pre Stage: Before the message has affected the entity.

o Post Stage: After the message has affected the entity and all modifications are complete.

· Choose the Pipeline

o Parent Pipeline: Standard pipeline used for most operations. Ex (Create Contact).

o Child Pipeline: This is new for Microsoft CRM 4.0. If the operation that is triggering the event occurs because of another event, use the child pipeline. For example, if you want your plugin to fire when an Invoice detail is created by the system when you convert an Opportunity to an Invoice. In this case the child pipeline is going to catch the create message for the invoice product

o When you use the child pipeline, in order to use the ICrmService you usually have to put the event in the Asynchronous Execution Mode.

Now you have created and registered your first plugin. This comes with a lot of responsibility. Make sure to check the Microsoft CRM server’s Application Event Logs regularly. This is where a majority of the errors that users might encounter will show up for your troubleshooting.