What is Plug-in

Plug-in

A plug-in is a .NET assembly that can be used to intercept events generated from the CRM system to

Perform a variety of actions. Performing a complicated update routine on CRM entities/attributes when it might be impractical to use JavaScript or business rules.

Isolation: Microsoft Dynamics CRM provides for registering plug-ins either in the sandbox (partial trust) or outside the sandbox (full trust).

Mode: You can set up plug-ins in synchronous or asynchronous mode. Synchronous mode starts the execution of the plug-in when the event is fired and blocks the CRM application process until the executed method finishes. This option is not recommended if you are performing a process that might take a long time to execute. Regardless of the method used, synchronous or asynchronous, a timeout limit of 2 minutes applies for plug-in executions. If a process needs more time, you should consider using a workflow or another custom background process.

You can check the execution status of asynchronous plug-ins from Settings > System Jobs. These

plug-ins are executed by the Microsoft Dynamics CRM Asynchronous Processing Service, which is a

Windows service.

Stages: You can set up plug-in steps in the pre-stages (either pre-validation or pre-operation) or

post-stages (post-operation):

ØPre-Stage :This stage is divided into pre-validation and pre-operation and sends control to the

                       plug-in before the real event is executed in the core system.
ØPost-Stage :This stage is executed after the real event has executed in the core system.

IPlugin interface, you must implement the Execute method, as shown in the following code:

namespace myPlugIn

{

public class Class1 : IPlugin

{

public void Execute(IServiceProvider serviceProvider)

{

throw new NotImplementedException(); }}}

The following sections explain the main classes.

IServiceProvider:

The Execute method of the IPlugin interface has only one parameter, named serviceProvider, which

is IServiceProvider type. From this parameter, you can get the plug-in execution context by

IPluginExecutionContext context =

(IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

IExecutionContext:

From the IExecutionContext object, you can query all the property values associated with the

entity and event context where the method is being executed. This class contains the properties described in the following sections.

BusinessUnitId	The BusinessUnitId property returns the GUID (global unique identifier) of the business unit of the user making the request
CorrelationId	The CorrelationId property returns the GUID of the plug-in event instance. Every time the event fires, it generates a new GUID that can be read from this property. You can use this property for tracking and logging purposes, especially when you have more than one plug-in attached to the same event, to see whether the codes execute for the same event pipeline.
Depth	The Depth property returns the depth of the originated event. This property is of integer type and grows as the plug-in execution goes deeper. The maximum number for the Depth property is set to 8. A system administrator can increase this value by running the PowerShell command`
InitiatingUserId	The InitiatingUserId property returns the GUID of the user who initially invoked the operation.
InputParameters	The InputParameters property is a collection of the request parameters associated with the event. You can use this property to retrieve the entity object for which the event is fired: Entity entity = (Entity)context.InputParameters["Target"];

IsExecutingOffline:

The IsExecutingOffline property is used only for Outlook clients and returns whether the Outlook

client is running in online or offline mode. This property is a Boolean type where true = offline mode.

IsInTransaction:

The IsInTransaction property is used to determine whether the operation is participating in a SQL

transaction. This property is a Boolean type where true = is in transaction.

IsOfflinePlayback:

The IsOfflinePlayback property is used only for Outlook clients and returns whether the Outlook

client is transitioning from offline to online mode. This property is a Boolean type where true =

synchronizing with the server.

IsolationMode:

The IsolationMode property returns the IsolationMode mode in which the plug-in is running

(none or sandbox). This parameter is an integer type where 0 = none and 2 = sandbox.

MessageName:

The MessageName property returns the name of the event that invoked the plug-in. It is a string. These

are the supported messages for custom entities:

Assign

Create

Delete

GrantAccess

ModifyAccess

Retrieve

RetrieveMultiple

RetrieveSharesPrincipalsAndAccess

RevokeAccess

SetStateDynamicEntity

Update

System entities can support other system messages. Refer to the message-entity support for plug-ins.xlsx

file in the CRM SDK for a complete list of System entity–supported messages.

Mode:

The Mode property returns the mode in which the plug-in is running. It can be synchronous or

asynchronous. This parameter is an integer type where

0 = synchronous and 1 = asynchronous.

OperationCreatedOn:

The OperationCreatedOn property returns the datetime value of the SystemJob created for

execution of an asynchronous plug-in. This value is null in the case of a synchronous plug-in.

OperationId:

The OperationId property returns the operation GUID when the plug-in is running in asynchronous

mode and gives you the ID of the current system job. In synchronous mode, this value is always an empty GUID.

ParentContext:

The ParentContext property returns the context of the parent pipeline operation, which may happen

if the plug-in is registered in the pre- or post-operations. Sometime the plug-in requires another internal Messages to be executed and this property gives you the context of the parent execution.

PostEntityImages:

The PostEntityImages property contains the collection of the images with the properties’ names

and values after the system executes the core operation.

PreEntityImages:

The PreEntityImages property contains the collection of the images with the properties and values

before the system executes the core operation. This is very useful on post-stages to see what values the associated entity had before an update operation, for example.

Stage:

The Stage property gets the stage at which the synchronous plug-in execution is registered. It can have any of the following values:
Ø  10 = pre-validation
Ø  20 = pre-operation
Ø  40 = post-operation

IOrganizationServiceFactory:

If you need to create an instance of the organization service, you can do it by using the

IOrganizationServiceFactory instance. The service instance returned by IOrganizationServiceFactory has the method CreateOrganizationService, which is used get an instance of IOrganizationService.

Here is an example of how to use IOrganizationService and the CreateOrganizationService method:

namespace myPlugIn

{
 public class Class1 :

IPlugin

{ public void Execute(IServiceProvider serviceProvider)

{

IPluginExecutionContext context = (IPluginExecutionContext)

serviceProvider.GetService(typeof(IPluginExecutionContext));

IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)

serviceProvider.GetService(typeof(IOrganizationServiceFactory));

IOrganizationService service = serviceFactory.CreateOrganizationService

(context.UserId); }}}

IOrganizationService:

To use the CRM services, you need to get an instance of IOrganizationService, which provides programmatic access to metadata and data for an organization.

The service instance returned by IOrganizationService has the following methods:

ØAssociate:Used to create a link between records.

ØCreate:Used to create records.

ØDelete:Used to delete records.

ØDisassociate:Used to remove a link between records.

ØExecute:Used, for example, to execute Fetch queries.

ØRetrieve:Used to retrieve a record.

ØRetrieveMultiple:Used to retrieve more than one record.

ØUpdate:Used to update records.