Share via

Register and Deploy Plug-Ins

  • Article

 

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

Plug-ins and custom workflow activities are custom code that you develop to extend the existing functionality of Microsoft Dynamics 365. Before a plug-in or custom workflow activity can be used, it must be registered with the server. You can programmatically register plug-ins and custom workflow activities with Microsoft Dynamics 365 (online & on-premises) by writing registration code using certain SDK classes. However, to ease the learning curve and to speed up development and deployment of custom code, a plug-in and custom workflow activity registration tool is included in Bin folder of the SDK. Download the Microsoft Dynamics CRM SDK package.

While this topic focuses primarily on plug-ins, most of the information is also applicable to custom workflow activities. One difference between the two is that for custom workflow activity assemblies, you register just the assembly. For plug-ins, you register the plug-in assembly and one or more steps per plug-in. For more information about custom workflow activities, see Custom workflow activities (workflow assemblies).

System_CAPS_security Security Note

Do not register any plug-in or custom workflow activity unless it is obtained from a reliable and trusted source.

For more information about how to package your plug-ins as solution components, see Package and distribute extensions using solutions.

In This Topic

Plug-in Registration Tool

Plug-in Storage

Deployment

Assembly Versioning and Solutions

Security Restrictions

Register Plug-ins Programmatically

Enable or Disable Custom Code Execution

Plug-in Registration Tool

The Plug-in Registration tool provides a graphical user interface and supports registering plug-ins and custom workflow activities with Microsoft Dynamics 365. However, plug-ins and custom workflow activities can only be registered in the sandbox (isolation mode) of Microsoft Dynamics 365 (online).

For more information about how to register and deploy a plug-in by using the tool, see Walkthrough: Register a plug-in using the plug-in registration tool. The tool can be added to the Visual StudioTools menu as an external tool to speed up the development process.

Plug-in Storage

For an on-premises deployment, plug-ins that are not registered in the sandbox can be stored in the Microsoft Dynamics 365 server's database or the on-disk file system. We strongly recommend that you store your production-ready plug-ins in the Microsoft Dynamics 365 database, instead of on-disk. Plug-ins stored in the database are automatically distributed across multiple Microsoft Dynamics 365 servers in a data center cluster. On-disk storage of plug-ins is useful for debugging plug-ins using Microsoft Visual Studio. However, you can debug a plug-in that is stored in the database. For more information, see Debug a plug-In.

Plug-ins registered in the sandbox must be stored in the database regardless of the Microsoft Dynamics 365 deployment (on-premises, IFD, or Online).

Deployment

For on-premises or Internet-facing (IFD) Microsoft Dynamics 365 installations, when you deploy plug-ins from another computer to the Microsoft Dynamics 365 server disk (on-disk deployment), the plug-in assembly must be manually copied to the server before registration. The assembly must be deployed to the <installdir>\Program Files\Microsoft CRM\server\bin\assembly folder on each server where the plug-in is to execute.

Plug-in registration should be done after the assembly has been copied to the …\bin\assembly folder on the server to prevent the situation where a system user causes an event in Microsoft Dynamics 365 to be raised but the registered plug-in assembly does not yet exist on the server. For server database deployment, the plug-in assembly is automatically copied during plug-in registration so that the earlier situation is not an issue.

Depending on your plug-in’s design, your plug-ins may require other referenced assemblies to run. Regardless of whether you deploy your plug-in to the database or disk, if your plug-in requires other assemblies to run, you must put copies of these assemblies in the global assembly cache on each server where the plug-in is to execute. This does not apply to a Microsoft Dynamics 365 (online) server because you do not have access to the global assembly cache on that server.

To move a plug-in from a development environment to a staging or production server

  1. On the development computer, build the plug-in code. Do not include debug information. Optimize the plug-in for performance.

  2. Register the plug-in in the Microsoft Dynamics 365 server database.

  3. Using the Microsoft Dynamics 365 web application, create a solution or use an existing one, and add the plug-in to that solution.

  4. After you have added any other desired components to the solution, export the solution.

  5. Import the solution on to the staging or production server.

Assembly Versioning and Solutions

Plug-in assemblies can be versioned using a number format of major.minor.build.revision defined in the Assembly.info file of the Microsoft Visual Studio project. Depending on what part of the assembly version number is changed in a newer solution, the following behavior applies when an existing solution is updated through import.

  • The build or revision assembly version number is changed.

    This is considered an in-place upgrade. The older version of the assembly is removed when the solution containing the updated assembly is imported. Any pre-existing steps from the older solution are automatically changed to refer to the newer version of the assembly.

  • The major or minor assembly version number, except for the build or revision numbers, is changed.

    When an updated solution containing the revised assembly is imported, the assembly is considered a completely different assembly than the previous version of that assembly in the existing solution. Plug-in registration steps in the existing solution will continue to refer to the previous version of the assembly. If you want existing plug-in registration steps for the previous assembly to point to the revised assembly, you will need to use the Plug-in Registration tool to manually change the step configuration to refer to the revised assembly type. This should be done before exporting the updated assembly into a solution for later import.

For more information about solutions, refer to Introduction to solutions.

Security Restrictions

There is a security restriction that enables only privileged users to register plug-ins. For plug-ins that are not registered in isolation, the system user account under which the plug-in is being registered must exist in the Deployment Administrators group of Deployment Manager. Only the System Administrator user account or any user account included in the Deployment Administrators group can run Deployment Manager.

Important

For non-isolated plug-ins, failure to include the registering user account in the Deployment Administrators group results in an exception being thrown during plug-in registration. The exception description states "Not have enough privilege to complete Create operation for an SDK entity."

The system user account under which the plug-in is being registered must have the following organization-wide security privileges:

  • prvCreatePluginAssembly

  • prvCreatePluginType

  • prvCreateSdkMessageProcessingStep

  • prvCreateSdkMessageProcessingStepImage

  • prvCreateSdkMessageProcessingStepSecureConfig

For more information, see Security role and privilege reference and The security model of Microsoft Dynamics 365.

For plug-ins registered in the sandbox (isolation mode), the system user account under which the plug-in is being registered must have the System Administrator role. Membership in the Deployment Administrators group is not required.

Register Plug-ins Programmatically

The key entity types used to register plug-ins and images are: PluginAssembly, PluginType, SdkMessageProcessingStep, and SdkMessageProcessingStepImage. The key entity types used to register custom workflow activities are PluginAssembly and PluginType. Use these entities with the create, update, retrieve, and delete operations.

For more information on images, see Understand the data context passed to a plug-in.

Enable or Disable Custom Code Execution

You can use Windows PowerShell to enable or disable custom code, including plug-ins and custom workflow activities, on the server as described here. Alternatively, you can use the Deployment Web service. For more information, see Deployment entities and deployment configuration settings to set the CustomCodeSettings.AllowExternalCode property.

To enable custom code execution

  1. Open a Windows PowerShell command window.

  2. Add the Microsoft Dynamics 365 PowerShell snap-in:

    Add-PSSnapin Microsoft.Crm.PowerShell

  3. Retrieve the current setting:

    $setting = get-crmsetting customcodesettings

  4. Modify the current setting:

    $setting.AllowExternalCode="True"

    set-crmsetting $setting

  5. Verify the setting:

    get-crmsetting customcodesettings

To disable custom code execution

  1. Open a Windows PowerShell command window.

  2. Add the Microsoft Dynamics 365 PowerShell snap-in:

    Add-PSSnapin Microsoft.Crm.PowerShell

  3. Retrieve the current setting:

    $setting = get-crmsetting customcodesettings

  4. Modify the current setting:

    $setting.AllowExternalCode=0

    set-crmsetting $setting

  5. Verify the setting:

    get-crmsetting customcodesettings

See Also

Plug-in development
Debug a plug-In
Plug-in isolation, trusts, and statistics
Package and distribute extensions using solutions
Privileges by entity

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright