Event Execution Pipeline

banner art

[Applies to: Microsoft Dynamics CRM 4.0]

Find the latest SDK documentation: CRM 2015 SDK

The Microsoft Dynamics CRM event processing subsystem executes plug-ins based on a message pipeline execution model. A Web service method call by a plug-in or other application results in a message being created in the Microsoft Dynamics CRM platform. The message contains business entity information and core operation information. The message is passed through the event execution pipeline where it can be read or modified by the platform core operation and any registered plug-ins.

The following figure illustrates the overall architecture of the Microsoft Dynamics CRM platform with respect to both synchronous and asynchronous event processing.

Synchronous and asynchronous event processing diagram

The event execution pipeline processes events either synchronously or asynchronously. The platform core operation and any plug-ins registered for synchronous execution are executed immediately and in a well defined order. Plug-ins registered for asynchronous execution are queued with the Asynchronous Service and executed at a later time. Synchronous plug-ins are executed before any workflows execute, assuming both are registered for the same data change event.

The event pipeline is divided into 5 stages, of which only 2 are available to custom developed plug-ins. Multiple plug-ins that are registered in each stage can be further be ordered (ranked) within that stage during plug-in registration using the Event Framework plug-in registration API.

Stage Stage Name Description
Pre-Event BeforeMainOperationOutsideTransaction Stage in the pipeline for plug-ins that are to execute before the main system operation. Pre-Event is raised before the platform core operation and before database transactions are started. For more information, see Inclusion in Database Transactions.
Pre-Event BeforeMainOperationInsideTransaction For internal use only.
Platform Core Operations MainOperation In-transaction main operation of the system, such as create, update, delete, and so on. No custom plug-ins can be registered in this stage.
Post-Event AfterMainOperationInsideTransaction For internal use only.
Post-Event AfterMainOperationOutsideTransaction Stage in the pipeline for plug-ins which are to execute after the main operation. In general plug-ins registered in this stage do not participate in the database transaction. For more information, see Inclusion in Database Transactions.

Note Validation (privilege checks) of the system user account under which a plug-in executes occurs after the Pre-Event stage. Use caution when registering a pre-event plug-in that modifies data in an external data store because the user has not yet been validated in Microsoft Dynamics CRM when the plug-in code executes.

Whenever application code or a workflow invokes a Microsoft Dynamics CRM Web service method, a state change in the system occurs that raises an event. The information passed as a parameter to the Web service method is internally packaged up into a Request message and processed by the pipeline. The information in the Request message is passed to the first plug-in registered for that event where it can be read or modified before being passed to the next registered plug-in for that event and so on. Plug-ins receive the message information in the form of context that is passed to their Execute method. The message is also passed to the platform core operation.

Plug-ins can be registered to execute before or after the core platform operation. Pre-event registered plug-ins receive the Request message first and can modify the message information before the message is passed to the core operation. After the core platform operation has completed, the message is passed to the registered post-event plug-ins. These plug-ins have the opportunity to modify the message before the final result, known as the Response, is returned to the application or workflow that invoked the original Web service method call.

A pre-event registered plug-in that passes a specific exception (InvalidPluginExecutionException) back to the platform cancels the core operation, any pre-event or post event registered plug-ins that have not yet executed, and any workflow that is triggered by the same data change event that the plug-in was registered for.

Because a single Microsoft Dynamics CRM server can host more than one organization, the execution pipeline is organization specific. There is a virtual pipeline for every organization that is defined in Microsoft Dynamics CRM. Plug-ins registered with the pipeline can only process business data for a single organization. A plug-in that is designed to work with multiple organizations must be registered with each organization's execution pipeline.

See Also


Other Resources

© 2010 Microsoft Corporation. All rights reserved.