Walkthrough: Register a Plug-in Using the Plug-in Registration Tool

Walkthrough: Register a Plug-in Using the Plug-in Registration Tool

[Applies to: Microsoft Dynamics CRM 2011]

This walkthrough demonstrates how to register a plug-in by using the Plug-in Registration tool that is provided in the SDK download. 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 2011 deployment where your user account has the System Customizer or System Administrator role.

The following prerequisites must be completed before starting this walkthrough:

  • Obtain the PluginRegistration.exe tool. As of version 5.0.13 of the SDK, you can find the tool’s executable file in the Bin folder of the SDK download. In previous SDK releases, you had to build the tool from source code provided in the Tools\PluginRegistration folder.

  • To run the Plug-in Registration tool with Microsoft .NET Framework 4, you must first install the Windows Identity Foundation. However, if you have installed Microsoft .NET Framework 4.5 on your development box, you do not need to install the Windows Identity Foundation because it is included in .NET 4.5.

  • Obtain access to a Microsoft Dynamics CRM 2011 or Microsoft Dynamics CRM Online 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.

Connect to the Microsoft Dynamics CRM Server

  1. Run the Plug-in Registration tool.

    The Microsoft.Crm.Sdk.Proxy.dll and Microsoft.Xrm.Sdk.dll assemblies must be in the same folder as the tool’s executable or in your computer’s global assembly cache in order for the tool to run.

  2. Click Create New Connection.

  3. In the Connections pane, under Connection Information, type a name for the connection, the URL of the server where the Microsoft Dynamics CRM discovery service is hosted, and your logon user name. For example, the discovery URL for Microsoft Dynamics CRM Online in North America is https://disco.crm.dynamics.com and the user name is your Microsoft Office 365 account user name. For the complete list of Microsoft Dynamics CRM Online discovery service URLs, see the topic Discover the URL for Your Organization with IDiscoveryService Web Service. The values shown in the following figure are for a fictitious on-premises server.

    Connection form fields

  4. Select the Use Saved Credentials option if your logon credentials are saved in the Windows credential cache on your computer. Otherwise, do not select this option; you will be prompted to enter your password.

  5. Click Connect.

You should see a list of available organizations that you belong to in the Connections pane.

Register a Plug-in Assembly

  1. Select an organization in the Connections pane.

  2. From the Register menu, and then click Register New Assembly.

    Register Assembly menu item

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

  4. In the Select Plug-in Assembly dialog box, move 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 Open.

  5. In the Step#2: Select the Plugin & Workflows and Activities to Register section, expand the SamplePlugins assembly to view all plug-ins in that assembly. Select only the Microsoft.Crm.Sdk.Samples.FollowupPlugin plug-in.

  6. In Step#3: Specify the Isolation Mode section, select the Sandbox option.

  7. In Step#4: Specify the Location where the Assembly should be stored section, select the Database option.

    Register New Assembly dialog

  8. Click Register Selected Plugins. Click OK to close the dialog boxes.

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 the Plug-in for an Event

  1. Select (Assembly) SamplePlugins in the tree view, move to the Register menu, and then click Register New Step.

    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 how the plug-in is to be executed.

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

    Register New Step dialog

    *If you want to register the plug-in to execute immediately (for testing purposes), select Synchronous.

  3. Click Register New Step.

  4. Expand the (Assembly) SamplePlugins node 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.

    To unregister the step, plug-in, or assembly, select its node in the tree, and then click Unregister.

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.

Test the Plug-in

  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

Microsoft Dynamics CRM 2011
Send comments about this topic to Microsoft.
© 2013 Microsoft Corporation. All rights reserved.

Community Additions

© 2016 Microsoft