Programming Microsoft Dynamics CRM 4.0: Plug-ins

The Event Execution Pipeline

Now that we implemented a basic plug-in, let’s step back and look at the bigger picture. Plug-ins run within an execution pipeline specific to the message being executed. Also executing within the pipeline is the core operation, which is implemented by Microsoft Dynamics CRM 4.0. The core operation typically consists of a database operation—either retrieving, updating, inserting, or deleting records. For example, when a RetrieveMultiple request is executed, the core operation is the selection of data from the database. Figure 5-5 illustrates the various stages of the event execution pipeline.

Figure 5-5. The event execution pipeline

Supported Messages and Entities

When trying to determine how to register a plug-in or even what is possible to hook into, you often find yourself wondering which messages exist for any given entity. The CRM SDK includes a Microsoft Office Excel spreadsheet that lists all the events that can be registered for and their corresponding entities. The file is named Plug-in Message-Entity Table.xls and is located in the Tools subfolder of the SDK.

This spreadsheet includes filterable columns and can be an excellent tool when you are trying to determine which messages an entity supports—or when you are just trying to brainstorm creative solutions. From this list you can see that several messages, such as Import, Export, and Publish, are not even tied to an entity. Figure 5-6 shows the spreadsheet filtered to only display messages supported by the Account entity.

Figure 5-6. The plug-in message entity spreadsheet

Parent and Child Pipelines

Some events will in turn cause other events to be executed. When this happens, a secondary pipeline is created for this event and is referred to as a child pipeline. For example, when an Opportunity is converted to an Account, the Create event is executed in a child pipeline. If you want to handle the creation of an account in this scenario, you need to specify Child as the InvocationSource when registering your plug-in step.

Typically, plug-ins only execute outside the main database transaction and cannot cause a rollback to occur. However, when a plug-in is running inside a child pipeline, it is executing inside the parent pipeline’s transaction, and if the plug-in throws an exception, the parent’s transaction will be rolled back.

CAUTION

One additional point to be aware of is that when you run a plug-in inside a child pipeline, you cannot use the IPluginExecutionContext interface’s CreateCrmService method. If you do, an exception is thrown. The use of the CreateCrmService method was intentionally disabled in child pipelines because it would be too easy to cause an infinite loop or a database deadlock if it were enabled. If you absolutely need to talk back to the CRM services inside a child pipeline, you can manually create a CrmService, but be sure to use it with caution. Additionally, any calls you make with your own CrmService run within their own thread and are outside transactions in which the plug-in executes. This means that if the transaction is rolled back for any reason, changes made with your instance of CrmService will not be undone.