Export (0) Print
Expand All

Plug-ins, Part 1: The Big Picture (Microsoft Dynamics CRM 4.0)

Peter Hecke
Microsoft Corporation

January 2009

Summary

The Microsoft Dynamics CRM 4.0 system covers the basic business needs of most users in sales, marketing, and customer support organizations. However, there are times when you might want to alter the system for the unique data storage and processing needs of your organization. The Microsoft Dynamics CRM SDK provides a number of ways to customize or enhance the CRM system. This article introduces one such SDK technology known as plug-ins. A plug-in is custom computer code that is compiled and registered with the Microsoft Dynamics CRM system in order to alter or extend the systems out-of-box functionality.

Applies To

Microsoft Dynamics CRM 4.0

Introduction

In this multi-part Getting Started series of articles on plug-in technology, I will present a subset of the Microsoft Dynamics CRM SDK technical information in an easier to understand format and augment it in certain areas for improved clarity. Along the way I hope to add new information to go beyond just understanding the technology. As the author of the plug-in section in the SDK documentation, I have learned ways to improve the plug-in development environment, how to improve plug-in design for increased performance, and more. In this article series, I hope to pass on some of this information and ease the learning curve associated with plug-in development.

The information in this article is written to augment the plug-in information presented in the Microsoft Dynamics CRM SDK. Consult the SDK for additional information about the topics presented here.

What are Plug-ins

A plug-in is custom business logic (code) that you can integrate with Microsoft Dynamics CRM 4.0 to modify or augment the standard data processing behavior of the platform. Plug-in code is compiled into an assembly and registered with the Microsoft Dynamics CRM platform. The registration process identifies the specific conditions under which the plug-in should execute and what kind of business data should be provided to the plug-in.

A Simple Plug-in

The following sample code shows the minimum code needed to implement a plug-in. When executed, this plug-in simply displays “Hello world!” in a dialog of the Microsoft Dynamics CRM Web application.


using System;
using Microsoft.Crm.Sdk;
using Microsoft.Crm.SdkTypeProxy;

namespace MyPlugins
{
   public class HelloWorldPlugin: IPlugin
   {
      public void Execute(IPluginExecutionContext context)
      {
         // Call the Microsoft Dynamics CRM Web services here or perform
         // some other useful work.
         throw new InvalidPluginExecutionException("Hello world!");
      }
   }
}


Imports System 
Imports Microsoft.Crm.Sdk 
Imports Microsoft.Crm.SdkTypeProxy 

Namespace MyPlugins 
    Public Class HelloWorldPlugin 
        Implements IPlugin 
        Public Sub Execute(ByVal context As IPluginExecutionContext) 
            ' Call the Microsoft Dynamics CRM Web services here or perform 
            ' some other useful work. 
            Throw New InvalidPluginExecutionException("Hello world!") 
        End Sub 
    End Class 
End Namespace 

While this plug-in does not do anything terribly useful, it still contains the key elements of plug-in design which includes:

  • Importing the Microsoft.Crm.Sdk and Microsoft.Crm.SdkTypeProxy namespaces.

  • Defining a class that is derived from the IPlugin interface.

  • Implementing an Execute method that is required by the IPlugin interface.

As a plug-in developer, your primary job is to add code to the plug-in’s Execute method that performs the desired business data operation. The next section of this article discusses the kinds of operations a plug-in can perform.

What can Plug-ins Do

Plug-ins have access to most of the capabilities provided by the Microsoft Dynamics CRM Web services. Your plug-in code will use SDK classes and methods to perform such operations as creating, retrieving, updating, or deleting entities (business objects) in the CRM database. Plug-ins can alter the business data that is currently being processed by the platform or even stop the current platform operation from occurring.

Below are some scenarios that identify typical uses for plug-ins:

  • Data Auditing – a plug-in can compare the before and after data changes to an entity and log those changes to a database. The log could later be read as a report.

  • Data Lookup – a plug-in could make use of an external data source to obtain relevant data and automatically fill in or modify entity attributes. For example, let’s assume a customer support representative creates a new case and enters the customer’s zip code but leaves the city and state blank. The plug-in could access an external Web service, which does a zip code to city/state lookup, and populate the empty city/state fields in the case.

  • Entity creation, deletion, modification, and retrieval – a plug-in can perform these types of operations to entities and their attributes. This capability also applies to entities other than the entity that the plug-in was executed for.

When to use Plug-ins

As a developer interested in extending or customizing Microsoft Dynamics CRM, you have several methods of accomplishing your task. The relevant technologies provided by the SDK that you can make use of include adding client side JavaScript code to forms, writing plug-ins, writing workflows, or adding custom ASP.NET pages. The technology you choose is dependent on the task that you need to perform. Because this article is about plug-ins, I will focus on that technology. However, I will briefly discuss workflows because there is some overlap in functionality between what you can accomplish in plug-ins and workflows.

Below is a table that summarizes some of the characteristics of plug-ins and workflows.

 

Criteria Plug-in Workflow

Executes before or after the core platform operation (Create, Update, Delete, etc.)

Executes immediately before or after the core operation (synchronous). Can also be queued to execute after the core operation (asynchronous).

Is queued to execute after the core operation (asynchronous).

Performance impact on the Microsoft Dynamics CRM platform

Synchronous plug-ins can increase the platform’s response time as they are part of the main platform processing. A poorly designed plug-in could hang the platform.

Less of a negative impact on platform response time.

Security restrictions

To register a plug-in with the platform requires a System Admin or System Customizer security role and membership in the Deployment Administrator group.

Users can interactively create worksflows in the Web application. However, in order to register custom workflow activities, the deploying user must have the same security roles as required for registering plug-ins.

Microsoft Dynamics CRM version (SKU) support

Not supported in Microsoft Dynamics CRM Online. May be supported in partner hosted installations.

Workflows without custom activities are supported by all product versions. Workflows with custom activities are supported the same as plug-ins.

Best application is for tasks which require a short or long amount of computing time

A plug-in registered for synchronous execution is best used for short processing tasks while a plug-in registered asynchronously can be used for process intensive operations. However, an asynchronous plug-in can only execute after the core platform operation has completed.

Either short or long processing tasks

Can be executed while the Outlook client is online or offline

Both online and offline are supported

Workflows do not execute on the offline Outlook client host computer.

Process and data persistence

Plug-ins execute to completion.

Workflows can be paused, postponed, cancelled, and resumed through SDK calls or by the user through the Web application. The state of the workflow is automatically saved before it is paused or postponed.

There are scenarios in which you must use a (synchronous) plug-in. For example, if you need to execute custom code immediately before or after the core platform operation executes and before the result of the operation is returned from the platform. Because workflows and asynchronous plug-ins are queued to execute some time after the core operation executes to completion, you are not guaranteed when they will run. On the other hand if you want to add custom functionality to Microsoft Dynamics CRM Online, only a workflow without custom activities is supported.

As you can see, there is an overlap in functionality between what kinds of operations a plug-in and a workflow can perform. As a developer, you will have to evaluate both technologies and decide on the one that best suits your business objectives after taking into account deployment, performance, and maintenance concerns of your plug-in or workflow solution.

For more information, see Workflows and Custom Workflow Activities. A related blog post named Plug-in or Workflow? is also available.

Message Processing in Microsoft Dynamics CRM

Knowing how to write and deploy plug-ins requires a certain knowledge of the internal data processing architecture of Microsoft Dynamics CRM. The following sections describe the key elements of the message processing pipeline that is the run-time environment in which plug-ins execute.

Messages and Requests

A message represents a Web service operation that the Microsoft Dynamics CRM platform is to perform. There are three Microsoft Dynamics CRM Web services available to SDK applications: CrmService, MetadataService, and CrmDiscoveryService. Each of these Web services provides support for numerous messages. However, only the messages in the CrmService Web service are available to plug-ins. The SDK Programming Reference documentation contains a complete list of messages that are supported by each Web service.

For more information, see CrmService Messages, MetadataService Messages, and CrmDiscoveryService Messages.

A request is a class in the SDK API that represents a message or a message and entity combination. The name of the request class describes the operation that is to be performed and optionally the related entity. For example, a request class named AddItemCampaignRequest represents the operation of adding an item to a campaign entity, where AddItem is the message. There are also request classes that do not relate to a particular entity. For example, the AssignRequest class represents the Assign message. These types of request classes often contain a target entity property that you use to indicate what entity to perform the intended operation on. Once set, the request class properties contain all business data required by the platform to perform the intended operation.

The Microsoft Dynamics CRM platform architecture supports the concept of a message processing pipeline. A message is sent to a Web service, processed by the internal platform pipeline, and the result (called a response) is returned to the caller of the Web service. A plug-in or other type of application can send a message to the platform pipeline for processing by creating a request and passing that request as a parameter to the Web Service’s Execute method.


// Create the request object.
WhoAmIRequest userRequest = new WhoAmIRequest();

// Execute the request.
WhoAmIResponse user = (WhoAmIResponse) service.Execute(userRequest);

The response returned from the Web service Execute method contains data that is the result of processing the message.

Within the IPlugin.Execute method of your plug-in class you can create requests and execute them through the Web services in order to perform whatever data operation your business needs require.

There is an Excel spreadsheet that ships in the Tools folder of the SDK download that lists all CrmService Web service message and entity combinations that you can register plug-ins for. The column headings of the spreadsheet have drop-down data filters that can be used to restrict the list to the entity and message combinations you are looking for.

For more information, see Supported Messages for Plug-ins, CrmService Execute Method, MetadataService Execute Method, and CrmDiscoveryService Execute Method.

Event Pipeline

The message pipeline concept is implemented in the CRM platform as an event pipeline. The event pipeline performs sequential (synchronous) processing of a message and returns the result (called a response) to the platform. I use the term sequential processing because there are several points in the pipeline where business logic is executed as shown in the following diagram.

e3ce1347-6621-4b7e-98a0-0651844b2b5d

In the pipeline is the core platform operation. This is where the actual entity information processing (such as create, update, or delete) takes place. Immediately before and after the core platform operation are registration points where plug-ins containing custom code can be registered to execute. A plug-in that is registered for a pre-event, meaning before the core operation event, has the ability to modify the context (entity data) passed to the plug-in’s Execute method before passing the context on to the core operation. A pre-event plug-in can also prevent (cancel) the core operation. A plug-in that is registered for a post-event, meaning after the core operation event, has the ability to alter the context returned from the core operation and the response returned from the platform to the Web service caller. A plug-in registered asynchronously is a post-event plug-in that it is queued to be executed by the Asynchronous Service at a later time.

The event pipeline architecture provides the capability for a pipeline to initiate the execution of one or more subordinate pipelines in order to process an SDK request. The originating pipeline is known as the parent while each subordinate pipeline is called the child. Web service method calls, such as Execute, start a parent pipeline while internal platform calls start a child pipeline.

Let us look at an example of how this parent/child pipeline design works. For example, a parent pipeline that processes a CompoundUpdateRequest to update a salesorderdetail quantity would invoke a child pipeline to update the salesorderdetail and another child pipeline to update the associated salesorder total. However, even a simple request, such as CreateRequest for an account, can result in a child pipeline being executed.

When a complex request is processed by a pipeline, the pipeline first executes any registered pre-event plug-ins and the core platform operation. Next, the pipeline starts a child pipeline and temporarily suspends processing until the child pipeline has finished processing its request. After the child pipeline has completed, the parent pipeline can complete its post-event processing.

  1. Pipeline A : pre-events are processed.

  2. Pipeline A : core platform operation, child pipeline B executed.

  3. Pipeline B executes

    1. Pipeline B : pre-events are processed.

    2. Pipeline B : core platform operation.

    3. Pipeline B : post-events are processed.

  4. Pipeline A : post-events are processed.

As a plug-in developer, the significance of this parent/child pipeline design is that you must decide which pipeline your plug-in is to be registered with in order to accomplish the plug-in’s intended functionality. The parent pipeline processes the Web service message request. Child pipelines only process Create, Update, or Delete messages as required by the platform to process the parent pipeline’s message. To determine which message is being processed by a child pipeline, you must enable tracing in Microsoft Dynamics CRM. Information about how to enable tracing can be found in the Microsoft Dynamics CRM 4.0 Implementation Guide.

TipTip
A public domain plug-in is available that can log the context and message being processed by the parent and child pipelines. Refer to the LogContextToCRM plug-in on MSDN Code Gallery.

For more information, see Event Execution Pipeline, Parent and Child Pipelines, IPlugin.Execute, and IPluginExecutionContext.

Context

The IPlugin interface that your plug-in is derived from defines an Execute method that takes a parameter of type IPluginExecutionContext. The context contains information that describes the run-time environment that the plug-in is executing in, information related to the execution pipeline, and attribute values for the entity that is currently being processed by the pipeline.

Below is the IPluginExecutionContext class diagram.

a041ea9c-948f-435e-be2a-b56cae87978d

There is a lot of information in the context data structure. Note that the context instance property values are dependent on the message and entity being processed and the configuration settings used to register the plug-in. As a plug-in developer, you must learn how to register a plug-in so that required data is available to your plug-in and also to know where the data can be found in the context data structure. In this article I discuss a few context properties and save some of the other properties for a future article on writing and registering a plug-in.

When a platform event is fired for which a plug-in is registered, the platform creates and populates the context. The platform then calls the plug-in's Execute method, passing in the context as a parameter. The execution context is passed to each registered plug-in in the pipeline when they are executed. Each plug-in in the execution pipeline is able to modify writable properties in the context. For example, given a plug-in registered for a pre-event and another plug-in registered for a post-event, the post-event plug-in can receive a context that has been modified by the pre-event plug-in. The same situation applies to plug-ins that are registered within the same stage (pre-event or post-event).

For more information, see Plug-in Context.

Input and Output Parameters

The InputParameters property bag contains the data values stored in the properties of the message request instance that was passed to the Web service Execute method and is currently being processed in the event pipeline. This property bag is available to pre-event or post-event registered plug-ins.

The OutputParameters property bag contains the data that is the result of the core platform operation and which is returned to the caller of the Web service Execute method. This property bag is only available to post-event registered plug-ins as the core platform operation has not occurred yet when a pre-event plug-in executes.

By changing the contents of these property bags in your plug-in, you can change the data that is passed to the core platform operation or returned in the response instance to the caller of the Web service Execute method.

See Common Context for a detailed discussion of this lengthy subject.

Images

In the context are properties named PreEntityImages and PostEntityImages of type PropertyBag. These image property bags can contain copies (snapshots) of the entity’s attribute values before (pre) and after (post) the core platform operation. In the auditing scenario mentioned earlier in this article, an auditing plug-in would compare the property values in the pre and post image property bags to determine what entity attributes have changed. Another use of the images would be to obtain the entity’s attribute values in the plug-in without having to send a Retrieve request to the Web service, which takes more compute time. These image property bags are only available to a plug-in if requested when the plug-in is registered.

ImportantImportant
Only those entity attributes that are set to a value or null are included in the image property bags. Also, a pre image for a Create message and a post image for a Delete message are not available to a plug-in because the entity does not exist at that point in time.

Additional Information

This article discusses the nature of plug-ins, internal details on how they are executed, and provides information on the business data (context) that is passed to them at run-time. The next article (part 2) of this article series will focus on plug-in development and deployment.

For more detailed plug-in programming information, see the Plug-ins topic in the Microsoft Dynamics CRM 4.0 SDK.

For another introductory article on plug-ins, see Introduction to Plug-in Development for Microsoft Dynamics CRM 4.0.

Send Us Your Feedback about this Article

We appreciate hearing from you. To send your feedback, click the following link and type your comments in the message body.

noteNote
The subject-line information is used to route your feedback. If you remove or modify the subject line we may be unable to process your feedback.

Send Feedback

 

 
 

Community Additions

ADD
Show:
© 2014 Microsoft