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

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

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: Create a 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 365 (online & on-premises) 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.

• Obtain a system user account on a Microsoft Dynamics 365 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 365.

Connect to the Microsoft Dynamics 365 Server

1. Run the Plug-in Registration tool.

2. Click CREATE NEW CONNECTION.

3. In the Login dialog, select the deployment type radio button corresponding to the Microsoft Dynamics 365 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 365 (online), and the Office 365 button is for the Microsoft Online Services provider of Microsoft Dynamics 365 (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 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 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 365 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 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 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 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 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 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 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 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 365 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

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright