Walkthrough: Register a plug-in using the plug-in registration tool

 

Applies To: Dynamics CRM 2013

This walkthrough demonstrates how to register a plug-in by using the Plug-in Registration tool that is provided in the SDK. The plug-in to register is the FollowupPlugin from the Sample: Basic plug-in topic.

The plug-in is to be registered on the account entity, CreateRequest message, on a post-event, and in the sandbox. The plug-in can be registered on any Microsoft Dynamics CRM 2013 and Microsoft Dynamics CRM Online deployment where your user account has the System Customizer or System Administrator role.

The following prerequisites must be completed before starting this walkthrough:

• Get the PluginRegistration.exe tool, located in the Tools\PluginRegistration folder of the SDK. Download the Microsoft Dynamics CRM SDK package.

• To run the Plug-in Registration tool, you must first install or enable Windows Identity Foundation. For more information, see Install Windows Identity Foundation (WIF) 3.5.

• Obtain a system user account on a Microsoft Dynamics CRM server.

• Your user account must have the System Customizer or System Administrator role. See How role-based security can be used to control access to entities in Microsoft Dynamics CRM 2013.

Connect to the Microsoft Dynamics CRM Server

1. Run the Plug-in Registration tool.

2. Click or tap CREATE NEW CONNECTION.

3. In the Login dialog, select the deployment type radio button corresponding to the Microsoft Dynamics CRM server you intend to register plug-ins with. The On-premises radio button includes an IFD deployment, the Online button is for the Windows Live provider of Microsoft Dynamics CRM Online, and the Office 365 button is for the Microsoft Online Services provider of Microsoft Dynamics CRM Online.

   Login window for an online deployment

   Login window for an on-premises deployment

4. If you check Always display list of available orgs, you are presented with a list of organizations that you belong to after you click or tap Login. This enables you to choose the organization that you want to register the plug-in with. Otherwise, your default organization is used.

5. Enter the indicated information about the server and login account, and then click or tap Login.

You should see a collapsed list of registered plug-in or custom workflow activity assemblies and service endpoints. The activity feeds and Microsoft.Crm.ObjectModel assemblies are required for Microsoft Dynamics CRM to function properly so the tool prevents you from altering them. Selecting an item in the list results in the Properties and Details tab panes displaying information about that list item.

The application’s main window

Register a plug-in assembly

1. Select an organization tab to make it active.

2. In the toolbar of the tab, click or tap Register and then Register New Assembly.

3. In the Register New Assembly dialog box, click the ellipses […] button to the right of the Step#1 field.

4. In the Open dialog box, navigate to the location of the compiled SamplePlugin.dll assembly. The default location is SDK\SampleCode\CS\Plug-ins\bin\Debug. Select the assembly, and then click or tap Open.

5. In the Step#2 section, expand the SamplePlugins assembly to view all plug-ins in that assembly. Select (check) only the Microsoft.Crm.Sdk.Samples.FollowupPlugin plug-in.

6. In the Step#3 section, select the Sandbox option.

7. In the Step#4 section, select the Database option.

   

   Dialog to register an assembly

8. Click or tap Register Selected Plugins. You can close any open dialog boxes.

   

   A registered plug-in shown in the tree view

   Tip

   Do you see an error in the Log area and the log contains the following message?

   <Message>Action failed for assembly 'SamplePlugins, Version=0.0.0.0, Culture=neutral, PublicKeyToken=829f574d80e89132': Deployment/Scalegroup does not allow running external code.</Message>

   If so, you must enable custom code on the server and try again. For more information see Enable or Disable Custom Code Execution.

The SamplePlugins.dll assembly and FollowupPlugin plug-in are now registered and deployed to the server. If you used the tool to register a custom workflow activity assembly, the next section on registering a step does not apply.

Register a plug-in step for an event

1. In the Registered Plug-ins & Custom Workflow Activities tree view, expand the (Assembly) SamplePlugins node and select a registered plug-in.

2. Navigate to the Register menu in the toolbar, and then click or tap Register New Step.

   Note

   Plug-ins are registered to execute when an event is processed in the event execution pipeline. Each event has a stage name and number to indicate its location in the pipeline either before or after the core platform operation. A step refers to the SDK message processing step entity that is used to configure when and how the plug-in is to be executed.

3. Complete the Register New Step dialog box as shown in the following figure.

   

   Dialog to register a new step

4. Click or tap Register New Step.

5. Expand the (Assembly) SamplePlugins node and sub-nodes to see the plug-in and step nodes you created. You can now close the tool, but you may want to keep it open until after you test the plug-in and unregister the assembly.

   Note

   To unregister the step, plug-in, or assembly, select its node in the tree, and then click or tap Unregister in the tool bar. To modify an assembly or step registration, double-click the assembly or step node in the tree view. Alternately, you can select the node and click or tap Update in the tool bar.

The plug-in is now registered to execute in the sandbox, for an account create event, and after the core operation executes. You registered the plug-in to run asynchronously since the creation of the follow-up task activity is not time critical. After an account is created, the plug-in will execute the next time the asynchronous service processes its queue.

Test the plug-in

After you register the plug-in you can optionally test its execution by using the following procedure.

1. Open the Microsoft Dynamics CRM web application for the same organization that you registered the plug-in assembly under.

2. Move to the workplace, select Accounts, and then click New.

3. In the Account Name box, type an account name, for example, Adventure Works Cycle, and then click Save & Close.

4. Double-click the form name in the Accounts grid to open the form.

5. Click Activities to display a list of related activities for the account. You should see the activity named “Send email to the new customer“ that the plug-in created.

6. If you registered the plug-in to run asynchronously, and did not select the Delete AsyncOperation if StatusCode = Successful option on the Register New Step form, there will be a new system job named “FollowupPlugin: Create of account”. To view the related system job, click Settings, and then click System Jobs. Double-click the system job previously mentioned.

You can now unregister the step, plug-in, and assembly if you want. You may also want to delete the system job and account that you created.

See Also

Plug-in development
Walkthrough: Configure assembly security for an offline plug-in
Register and Deploy Plug-Ins
Event execution pipeline
Plug-in isolation, trusts, and statistics
Supported messages and entities for plug-ins