Architecture and Related Components
The following figure illustrates the overall architecture of
the Microsoft Dynamics CRM platform with respect to both synchronous and
asynchronous event processing.
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. Synchronous plug-ins that are registered for the event are executed in a well-defined order. Plug-ins registered for asynchronous execution are queued by the Asynchronous Queue Agent and executed at a later time by the asynchronous service.
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. Synchronous plug-ins that are registered for the event are executed in a well-defined order. Plug-ins registered for asynchronous execution are queued by the Asynchronous Queue Agent and executed at a later time by the asynchronous service.
 Important |
|---|
| Regardless of whether a plug-in executes synchronously or asynchronously, there is a 2 minute time limit imposed on the execution of a (message) request. If the execution of your plug-in logic exceeds the time limit, a System.TimeoutException is thrown. If a plug-in needs more processing time than the 2 minute time limit, consider using a workflow or other background process to accomplish the intended task. |
Pipeline Stages
The event pipeline is divided into multiple stages, of which 4
are available to register custom developed or 3rd party plug-ins.
Multiple plug-ins that are registered in each stage can be further be
ordered (ranked) within that stage during plug-in registration.
| Event | Stage name | Stage number | Description | ||
|---|---|---|---|---|---|
| Pre-Event | Pre-validation | 10 | Stage in the pipeline for plug-ins that are to execute
before the main system operation. Plug-ins registered in this stage may
execute outside the database transaction.
|
||
| Pre-Event | Pre-operation | 20 | Stage in the pipeline for plug-ins that are to execute before the main system operation. Plug-ins registered in this stage are executed within the database transaction. | ||
| Platform Core Operation | MainOperation | 30 | 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. For internal use only. | ||
| Post-Event | Post-operation | 40 | Stage in the pipeline for plug-ins which are to execute after the main operation. Plug-ins registered in this stage are executed within the database transaction. | ||
| Post-Event | Post-operation (Deprecated) | 50 | Stage in the pipeline for plug-ins which are to execute after the main operation. Plug-ins registered in this stage may execute outside the database transaction. This stage only supports Microsoft Dynamics CRM 4.0 based plug-ins. |
Security Note Message Processing
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 OrganizationRequest message and processed by the pipeline. The information in the OrganizationRequest
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-in Registration
Plug-ins can be registered to execute before or after the core platform operation. Pre-event registered plug-ins receive the OrganizationRequest
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 then known as the OrganizationResponse.
The response is passed to the registered post-event plug-ins.
Post-event plug-ins have the opportunity to modify the message before a
copy of the response is passed to any registered asynchronous plug-ins.
Finally, the response is returned to the application or workflow that
invoked the original Web service method call.
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. 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.
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. 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.
| Note |
|---|
| In Microsoft Dynamics CRM 4.0, there existed a parent and a child pipeline. These pipelines have been consolidated into one pipeline for this release. A pre-event plug-in registered in the parent pipeline of Microsoft Dynamics CRM 4.0 is equivalent to registering in stage 10. A pre-event plug-in registered in the child pipeline of Microsoft Dynamics CRM 4.0 is equivalent to registering in stage 20. |
Inclusion in Database Transactions
Plug-ins may or may not execute within the database
transaction of the Microsoft Dynamics CRM platform. Whether a plug-in is
part of the transaction is dependent on how the message request is
processed by the pipeline. You can check if the plug-in is executing
in-transaction by reading the IsInTransaction property inherited by IPluginExecutionContext
that is passed to the plug-in. If a plug-in is executing in the
database transaction and allows an exception to be passed back to the
platform, the entire transaction will be rolled back. Stages 20 and 40
are guaranteed to be part of the database transaction while stage 10 and
50 may be part of the transaction.
Any registered plug-in that executes during the database transaction and that passes an exception back to the platform cancels the core operation. This results in a rollback of the core operation. In addition, any pre-event or post event registered plug-ins that have not yet executed and any workflow that is triggered by the same event that the plug-in was registered for will not execute.
Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online support the execution of plug-ins and custom workflow activities in an isolated environment. In this isolated environment, also known as a sandbox, a plug-in or custom activity can make use of the full power of the Microsoft Dynamics CRM SDK to access the organization web service. Access to the file system, system event log, certain network protocols, registry, and more is prevented in the sandbox. However, sandbox plug-ins and custom activities do have access to external endpoints like the Windows Azure cloud.
Microsoft Dynamics CRM collects run-time statistics and monitors plug-ins and custom workflow activities that execute in the sandbox. If the sandbox worker process that hosts this custom code exceeds threshold CPU, memory, or handle limits or is otherwise unresponsive, that process will be killed by the platform. At that point any currently executing plug-in or custom workflow activity in that worker process will fail with exceptions. However, the next time that the plug-in or custom workflow activity is executed it will run normally. There is one worker process per organization so failures in one organization will not affect another organization.
In summary, the sandbox is the recommended execution environment for plug-ins as it is more secure, supports run-time monitoring and statistics reporting, and is supported on all Microsoft Dynamics CRM deployments. In addition, Microsoft Dynamics CRM Online only supports execution of custom workflow activities if they are registered in the sandbox. Support for custom workflow activity execution in the sandbox is new for Microsoft Dynamics CRM 2011 Update Rollup 12 and Microsoft Dynamics CRM December 2012 Service Update.
Any registered plug-in that executes during the database transaction and that passes an exception back to the platform cancels the core operation. This results in a rollback of the core operation. In addition, any pre-event or post event registered plug-ins that have not yet executed and any workflow that is triggered by the same event that the plug-in was registered for will not execute.
Microsoft Dynamics CRM 2011 and Microsoft Dynamics CRM Online support the execution of plug-ins and custom workflow activities in an isolated environment. In this isolated environment, also known as a sandbox, a plug-in or custom activity can make use of the full power of the Microsoft Dynamics CRM SDK to access the organization web service. Access to the file system, system event log, certain network protocols, registry, and more is prevented in the sandbox. However, sandbox plug-ins and custom activities do have access to external endpoints like the Windows Azure cloud.
Microsoft Dynamics CRM collects run-time statistics and monitors plug-ins and custom workflow activities that execute in the sandbox. If the sandbox worker process that hosts this custom code exceeds threshold CPU, memory, or handle limits or is otherwise unresponsive, that process will be killed by the platform. At that point any currently executing plug-in or custom workflow activity in that worker process will fail with exceptions. However, the next time that the plug-in or custom workflow activity is executed it will run normally. There is one worker process per organization so failures in one organization will not affect another organization.
In summary, the sandbox is the recommended execution environment for plug-ins as it is more secure, supports run-time monitoring and statistics reporting, and is supported on all Microsoft Dynamics CRM deployments. In addition, Microsoft Dynamics CRM Online only supports execution of custom workflow activities if they are registered in the sandbox. Support for custom workflow activity execution in the sandbox is new for Microsoft Dynamics CRM 2011 Update Rollup 12 and Microsoft Dynamics CRM December 2012 Service Update.
Trusts
Developers have the option of registering their plug-ins in
the sandbox, known as partial trust, or outside the sandbox, known as
full trust. Full trust is supported for on-premises and Internet-facing
Microsoft Dynamics CRM deployments. For a Microsoft Dynamics CRM Online
deployment, plug-ins or custom workflow activities must be registered in
the sandbox (partial trust) where they are isolated as previously
described.
| Important |
|---|
| Custom workflow activities and plug-ins that were developed using the Microsoft Dynamics CRM 4.0 SDK are not supported for execution in the sandbox or by Microsoft Dynamics CRM Online. |
Run-time Statistics
The Microsoft Dynamics CRM platform collects run-time
information about plug-ins and custom workflow activities that execute
in the sandbox. This information is stored in the database using PluginTypeStatistic entity records. These records are populated within 30 minutes to one hour after the sandboxed custom code executes. See the PluginTypeStatistic
attributes to find out what information is collected. You can retrieve
this information by using the retrieve message or method.
Pre and Post Images
Pre and Post images contain snapshots of the primary entity’s attributes before and after the core platform operation. Microsoft Dynamics CRM populates the pre-entity and post-entity images based on the security privileges of the impersonated system user. You can specify to have the platform populate these properties when you register your plug-in. The entity alias value you specify during plug-in registration is used as the key into the image collection. Once your plugin and steps are registered, register new image using the plugin registration tool. You have to make sure to use the same name in the EntityAlias field which you will use to query in the plugin code. For
e.g.: PluginExecutionContext.PreEntityImages.Contains(“PreImageXML”), make sure to use “PreImageXML” as EntityAlias while registering image.
You will need to repeat same steps for post image as well. For best performance, only select attributes which are used in the plugin code to be passed in the pre and post images. Passing all attributes would slow down the plugin execution. There are some events where images are not available. Below is a quick summary of pre and postimage support in CRM 2011.
Pre and Post Images
Pre and Post images contain snapshots of the primary entity’s attributes before and after the core platform operation. Microsoft Dynamics CRM populates the pre-entity and post-entity images based on the security privileges of the impersonated system user. You can specify to have the platform populate these properties when you register your plug-in. The entity alias value you specify during plug-in registration is used as the key into the image collection. Once your plugin and steps are registered, register new image using the plugin registration tool. You have to make sure to use the same name in the EntityAlias field which you will use to query in the plugin code. For
e.g.: PluginExecutionContext.PreEntityImages.Contains(“PreImageXML”), make sure to use “PreImageXML” as EntityAlias while registering image.
You will need to repeat same steps for post image as well. For best performance, only select attributes which are used in the plugin code to be passed in the pre and post images. Passing all attributes would slow down the plugin execution. There are some events where images are not available. Below is a quick summary of pre and postimage support in CRM 2011.
No comments:
Post a Comment