Create and deploy plug-ins using the Developer Toolkit

 

Applies To: Dynamics CRM 2013

Your solution must contain a plug-in project before you can create a plug-in. More information: Create a new Developer Toolkit project

In This Topic

Plugins project

Create and deploy a plug-in

Add a step to a plug-in

Plugins project

The Plugins project contains a base class named Plugin that implements the Microsoft.Xrm.Sdk.IPlugin interface. All plug-in classes generated through the Create Plug-in option of the CRM Explorer will derive from this class. This class simplifies some of the common code that is required by many plug-ins, including the following:

• Obtaining execution context from the service provider.

• Obtaining the tracing service from the service provider.

• Instantiating the Organization Service proxy.

Additionally, the validation method verifies several typical plug-in events and provides a pattern for the developer to extend.

Initially, the implementation of the derived class calls the implementation of the base class before continuing with its own, more specific implementation. After validating that the plug-in should execute, the base class calls up to the Execute method of the derived class, passing through the execution context and Organization Service proxy.

More information: Write plug-ins to extend business processes

Create and deploy a plug-in

1. In CRM Explorer, locate the entity that you want to create the plug-in for. Right-click the entity and then select Create Plug-in.

   • If the current project already has an existing plug-in assembly registered, you can also use the Add Plugin shortcut menu option on the existing plug-in assembly and then select the entity you want it to apply to.

2. The Create Plug-in dialog box appears with the fields in the following table.

Field	Description
Project	The plug-in library project in your Visual Studio solution.
Class	A recommended class name based on the selected pipeline stage and message.
Primary Entity	The entity that must be processed by the execution pipeline for the plug-in to execute.
Secondary Entity	Some messages require a secondary entity. See the documentation on the specific message for more information.
Message	The message that must be processed by the Microsoft Dynamics CRM execution pipeline for the plug-in to execute.
Filtering Attributes	A list of entity attributes that cause the plug-in to execute when it is changed. A value of null causes the plug-in to execute if any of the attributes change. When you specify a message that supports filtering attributes, for example Update, an ellipsis (…) button is displayed that lets you select attributes from a list.
Run in Context	The system account that owns any data changes the plug-in makes. The Calling User is the logged on user who initiated the message to be processed. More information: Impersonation in plug-ins
Execution Order	The order, also known as rank, that plug-ins are executed in a pipeline stage. Plug-ins registered by using an order value of 1 are executed first, followed by plug-ins registered by using an order of 2, and so on. However, if there is more than one plug-in in a stage with the same order value, the plug-in with the earliest compilation date is called first.
Pipeline Stage	When the plug-in should execute: before (Pre) or after (Post) the core operation that processes the message. More information: Event execution pipeline
Deployment	Where the plug-in should be deployed: on the server, on Microsoft Dynamics CRM for Outlook with Offline Access, or both.
Execution Mode	For plug-ins registered to execute in a post stage, specify if you want them to execute immediately (synchronous) or queued to execute later (asynchronous). For post operations, specifying asynchronous execution gives you improved system performance compared to synchronous execution.
Description	A description of the step. Typically, you can describe the purpose of the step for other developers or administrators who might run the registration tool at a later date.
Unsecure Configuration	If you have written a constructor for the plug-in that takes one or two string arguments, any string values that you specify in these fields are passed to the plug-in constructor at run-time. More information: Write a plug-in
Secure Configuration
Pre Image Alias	A pre-image is a snapshot of the entity’s attributes before the core operation. The entity alias value that you specify is used by your plug-in code as the key into the image collection.
Parameters	The list of attributes to be included in the pre-image.
Post Image Alias	A post-image is a snapshot of the entity’s attribute after the core operation. The entity alias value that you specify is used by your plug-in code as the key into the image collection.
Parameters	The list of attributes to be included in the post-image.

3. In the Create Plugin dialog box, click OK to generate the plug-in code. This action also updates the RegisterFile.crmregister in the CRM Package project to store the plug-in registration information.

4. Open the class that is generated and locate this comment // TODO: Implement your custom Plug-in business logic. Add your custom plug-in business logic to that method.

5. In the Properties of the plug-in project, on the Signing tab, select the Sign the assembly check box and set the strong name key file of your choice.At a minimum, you must specify a new key file name. Do not protect your key file by using a password.

6. Right-click the CRM Package project and select Deploy.

   This builds the dependent projects and deploys the plug-in to the Microsoft Dynamics CRM server. Subsequent changes to the plug-in are pushed to the server during the build and deploy process.

Note

You may get the error: Error registering plug-ins and/or workflows. Public Assembly must have public key after you have signed the assembly as described in step 5, when the solution contains a workflow assembly project that is not signed. All plug-in and workflow projects in the solution must be signed.

Add a step to a plug-in

You can only add steps to a plug-in included in the current project. In the CRM Explorer plug-in, assemblies included in the current project will have a different icon as shown in the following table.

Plugin Icon	Description
	This plug-in assembly is part of the current solution
	This plug-in assembly is registered in the organization but isn’t part of the current solution.

1. Right-click a plug-in that is part of a plug-in assembly in the current solution and select Add Step.

2. In the Create Plug-in dialog box, configure your step. More information: Create and deploy a plug-in

See Also

Developer Toolkit for Microsoft Dynamics CRM 2013
Write plug-ins to extend business processes
Install or uninstall the Developer Toolkit
Developer toolkit features
Create a new Developer Toolkit project
Deploy a solution using the developer toolkit
Create and deploy workflow libraries using the Developer Toolkit
Create and deploy XAML workflows using the Developer Toolkit
Create and deploy web resources using the Developer Toolkit