Peter Hecke

Microsoft Corporation

February 2008

Applies To

Microsoft Dynamics CRM 4.0

Requires:

Microsoft Dynamics CRM 4.0

Microsoft® Visual Studio® 2005

Summary

Microsoft Dynamics CRM 4.0 on-premise supports extending the platform through the integration of custom business logic known as plug-ins. In Microsoft Dynamics CRM 3.0, these business logic extensions are known as callouts. Plug-ins execute in a richer run-time environment than before and have access to new product capabilities. This article provides an overview of the new plug-in capability, compares plug-ins to callouts, and discusses how to begin learning the new plug-in programming model.

Introduction

One method of customizing or extending the functionality of the Microsoft Dynamics CRM 4.0 on-premise product is through the integration of custom business logic (code). It is through this extension capability that you can add new data processing features to the product or alter the way business data is processed by the system. You can also define the specific conditions under which the custom business logic is to execute. Whether you are new to extending Microsoft Dynamics CRM or have been developing 3.0 callouts for some time, this article tells you what you need to know to get started learning about and writing plug-ins.

Microsoft Dynamics CRM Online does not support plug-ins. However, you can extend the functionality of the product by using workflows.

Comparing Plug-ins to Callouts

The programming model for adding business logic extensions to Microsoft Dynamics CRM has changed in the latest 4.0 SDK release as compared to the 3.0 release. This change was the direct result of our customers asking for access to more capabilities and run-time information in plug-in code. In addition, architectural changes and feature additions to the Microsoft Dynamics CRM 4.0 product necessitated changes to the programming model so that plug-ins could take advantage of the new platform capabilities.

What about your existing callouts? Do you have to throw them away and develop new plug-ins? The good news is that Microsoft Dynamics CRM 4.0 is backwards compatible with the callout programming model. Your existing callouts should continue to work along side any new plug-ins that you develop as long as you do not use any deprecated features. However, if you want to take advantage of the new Microsoft Dynamics CRM 4.0 capabilities and the rich information that is available at run time, you need make use of the plug-in programming model.

The following points highlight what has changed when comparing the new plug-in programming model to the previous callout model.

• Registration

  Callouts are registered by editing an XML configuration file that is stored in a specific folder on the Microsoft Dynamics CRM 3.0 server. In essence this is a static registration method. Changes to the configuration file require an IIS reset to apply the changes.

  Plug-ins are registered dynamically through a new registration API. No IIS reset is required. Sample tools to register plug-ins, complete with source code, are provided in the SDK.

  Plug-in registration is now more complex to learn, due to the more advanced plug-in programming model.

• Context

  Callouts received a basic amount of data at run-time about the user who initiated an operation in Microsoft Dynamics CRM and the entity being acted upon.

  Plug-ins receive a wealth of information at run-time. See the next topic for more information.

• Supported messages

  Callouts could only be executed in response to a subset of messages that were processed by the Microsoft Dynamics CRM platform.

  Plug-ins can execute in response to most messages being processed by the platform.

• Mode of execution

  Callouts were executed synchronously as part of the main execution thread of the platform. Callouts that performed a lot of processing could reduce overall system performance.

  Plug-ins can execute both synchronously and asynchronously. Asynchronous registered plug-ins are queued to execute at a later time and can incorporate process intensive operations.

What's New

In addition to the plug-in features mentioned in the previous topic, the following capabilities are also supported. 

• Infinite loop detection

  The Microsoft Dynamics CRM platform has the ability to terminate a plug-in that performs an operation which causes the plug-in to again be executed and so on resulting in a significant performance hit on the system.

• Plug-ins receive expanded run-time information (context)

  Information passed to plug-ins include: custom data, the conditions under which the plug-in was run, information included in the request and response messages that the system is processing, snapshots of entity attributes before and after the core system operation, and more. Plug-ins can also pass data between themselves as a form of inter plug-in communication.

• Execution dependency

  Plug-ins can be registered so as to be dependent with other plug-ins. Dependency defines an order to plug-in execution whereby one plug-in must run to completion before another plug-in executes.

• Database deployment

  Plug-ins can be deployed to the Microsoft Dynamics CRM database in addition to on-disk deployment. This result is automatic distribution to multiple Microsoft Dynamics CRM servers in a data center.

A Sample Plug-in

So you now know about the powerful plug-in capabilities and the extensive data passed to a plug-in at run-time. But what does plug-in code look like? Here is a very basic plug-in that displays "Hello world!" in a dialog to the user.

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!");
      }
   }
}

The real power of plug-ins lies in the extensive context information that is passed to the plug-in, the ability to alter some of that information as it passes through the system, and the ability to call Microsoft Dynamics CRM Web methods. Refer to the SDK documentation for more information.

How to Get Started

Whether you are new to developing Microsoft Dynamics CRM business logic extensions or are an experienced callout developer, the following information should get you up to speed quickly with the new plug-in development and registration programming models.

• SDK documentation – Contains lots of new material providing detailed information on extending Microsoft Dynamics CRM 4.0. Start by reading the Plug-ins topic.
  • Plug-in Walkthroughs – Follow step by step procedures to write and deploy plug-ins.
  • Quickstart Guide to Plug-in Development – Gets you started developing plug-ins quickly.
• SDK code samples – Includes sample tools to register plug-ins and also some sample plug-ins. The tool sample code demonstrates how to use the plug-in registration APIs.

If you are new to Microsoft Dynamics CRM SDK programming, you will need to learn about the Web services, security and entity models, and more in order to write plug-ins that perform useful operations. Consult the SDK documentation for more information.

Additional Information

This article provided a glimpse into some of the features and capabilities of the plug-in programming model. For more detailed programming information, see the Microsoft Dynamics CRM 4.0 SDK.

For more information on upgrading callouts and deprecated classes, see Upgrading from Microsoft Dynamics CRM 3.0 in the SDK.

Note that the SDK documentation and code samples are still being developed. We plan to issue quarterly updates of the SDK, so check the download site periodically. If you find that some reference documentation or code samples are missing, we are working on it!

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.

Note   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