Getting a head start developing Dynamics CRM plug-ins

In this article I will explain what Dynamics CRM plug-ins are and which tools you can use to speed up the development of CRM plug-ins. The goal of this article is not to explain the logic behind plug-ins in detail, you can look a the links outlined in the references section of this blog post for that. I will however provide you with the most important information to get you started building your first Dynamics CRM plug-in with Visual Studio 2015 using the different tools : Microsoft Dynamics CRM SDK Templates, Microsoft Dynamics 365 Developer Toolkit, Dynamics CRM & 365 Developer Extensions or JonasPluginBase

A plug-in is an event handler (packaged as a .NET assembly) that can be used to intercept events generated from the  Dynamics CRM system, to perform a number of actions in code.  Apparently the underlying architecture of plug-ins has not changed a lot since Dynamics CRM 2011 so developers who have building these for previous versions can still use the same code base. So in essence plug-ins are .NET classes that implement the Microsoft.Xrm.Sdk.iPlugin interface. One or more plug-in classes can be contained in a .NET assembly (class library) – so you can just create a new class library project, add a reference to the Microsoft.Xrm.Sdk.dll (part of the SDK), add a class which inherits from Microsoft.Xrm.Sdk.iPlugin and implement the Execute method. You will also need to add to sign your assembly with a strong name.

But to let CRM know that your code needs to run, you will need to register your assembly to be invoked as part of the message execution pipeline that occurs when a CRM message is being processed. So first you will need to define on which type of message you want to react (e.g. associate tasks upon creation of a new account, setting default values, etc …) – these can be common messages such as create, retrieve (read), update or delete but also specific messages such as AddToQueue. Most message types are available for extension but there are some exceptions – check out Supported messages and entities for plug-ins.

Another design decision that you have to make when registering your plug-in, is whether it needs to run synchronously or asynchronously. Do realize that the choice between synchronous or asynchronous is also defining at which stage you can register your plugin e.g. an asynchronous plugin will only run post-operation and is not part of the database transaction (See Event execution pipeline for more details about the different stages).

The third design decision you will have to make, is deciding where your code will execute – Dynamics CRM provides two different options:

• Full-trust (or non-isolated): synchronous plugins will run within the W3WP.exe process of IIS, and asynchronous plug-ins in the AsyncService which host the process. This is only possible in on-premise deployment and although slightly faster you will loose the benefits of …
• Sandbox execution (or isolated mode): executes in the Microsoft.Crm.Sandbox.Workerprocess.exe process This should be your default choice unless you have a good reason not to use sandbox execution. This is the only option for CRM Online deployment but also has some limitations such as a two minute execution limit but also provides some benefits such as collection of run-time statistics about plugins-ins and custom workflow activities that run in the sandbox.  – I recommend that you read Plug-in isolation, trusts and statistics for more information as well as Understanding plugin sandbox mode.

To actually built the logic for your plugin you will need to use iPluginExecutionContext which provides information about the execution of the plugin such as (See Understand the data context passed to a plug-in for more information)

• MessageName: name of the message in this case Create
• Stage: stage that a plugin is being invoked e.g. 20 for Pre-Operation
• PrimaryEntityName: name of the entity that triggered this message e.g. “lead”
• InputParameters: Parameters from the request message – e.g. for a createrequest there is parameter of type “target” which contain
• OutputParameters: Response message after the operation has completed

The next code sample shows how you use the PluginExecutionContext and how you leverage interfaces such as iTracingService (Provides a method of logging run-time trace information for plug-ins) and iOrganizationServiceFactory which allows you to create an instance of the organization service.

Option 1 : Dynamics CRM SDK Templates
As you noticed there is a quite a lot of plumbing code needed before you can get started. Fortunately there are alternative ways to start coding your CRM plugins such as the Microsoft Dynamics CRM SDK Templates (also part of the Dynamics CRM 2016 SDK). This provides a Visual Studio project template with a pluginbase class so that a lot of the repetitive plumbing code can be eliminated.

Option 2: Microsoft Dynamics 365 Developer Toolkit
Recently Microsoft also released an updated version of their CRM developer toolkit – Microsoft Dynamics 365 Developer Toolkit which is a set of Microsoft Visual Studio integration tools, focused on accelerating the development process. I recommend that you read Microsoft Dynamics 365 Developer Toolkit Series – Part 3  to get a feeling how you can use the Dynamics 365 Developer Toolkit.

Option 3: Dynamics CRM & 365 Developer Extensions
There are however also other tools out there such as the Dynamics CRM & 365 Developer Extensions from Jason Lattimer which is a very worthy replacement of the SDK Developer Toolkit. It contains a lot of templates and will accelerate your development of plugins and workflows by allowing for a one-click deploy directly from within Visual Studio but also contains building blocks for using unit test for your plug-ins. It currently supports Visual Studio 2012, 2013 and 2015.

Before you can use the CRM Developer Extensions you will need to change some settings in Visual Studio 2015 – go to Tools>Options and navigate to CRM Developer Extensions (See screenshot below)

Option 4: Microsoft Dynamics CRM/365 Plugin base class
Jonas Rapp also has a very light-weight and simple to use plugin-base class available which also includes tracing and timing information – check out https://github.com/rappen/JonasPluginBase

References:

• Write plug-ins to extend business processes (MSDN)
• Plug-in development (MSDN)
• Debugging solution for Plugin
• Event execution pipeline
• CRM Plugins – Stopping infinite loops and understanding PluginExecutionContext.Depth
• Dynamics CRM Deeper Look Into IOrganizationServiceFactory, IPluginExecutionContext and ITracingService
• Plugin on retrieve and retrievemultiple – how bad is it?
• Enabling Configurable Plugin Trace Levels
• CRM 2015 – Understanding impersonation in plugins and knowing when to use it
• CRM 2016 – Maximum plugin size
• How to register an early bound library within Dynamics CRM Online Sandbox Isolation Mode (Part 1)
• Debugging your plug-ins with the plug-in trace log
• Plugin pre-validation operation to show an error message as well as log the error
• I have been doing plugin parameters wrong for 7 years