This documentation is archived and is not being maintained.

Registering Plug-ins

Dynamics
banner art

[Applies to: Microsoft Dynamics CRM 4.0]

Find the latest SDK documentation: CRM 2015 SDK

Plug-in development and registration is a more complex process in Microsoft Dynamics CRM 4.0 compared to Microsoft Dynamics CRM 3.0. Plug-ins are passed much richer context at run time compared to Microsoft Dynamics CRM 3.0. Some information in the context is provided during plug-in registration and some is generated by the Microsoft Dynamics CRM system at run time. Plug-in registration is performed through custom code that uses new classes in the SDK.

To ease the learning curve and speed development and deployment of plug-ins, sample plug-in registration tools with complete source code are included in the SDK code samples. By using these tools, you can concentrate on learning plug-in development first and then develop your own custom registration tools. For more information about the tool sample code, see Sample Code.

Warning When plug-ins are registered in Microsoft Dynamics CRM, they become part of the primary operation of the Microsoft Dynamics CRM system. Do not register any plug-in unless it is obtained from a reliable and trusted source. Plug-ins that contain malicious code can have a severe effect on the system and cause Denial of Service type attacks.

Plug-in Registration Tools

Sample code for two plug-in registration tools is provided in the SDK\Tools folder of the SDK code samples. The PluginRegistration tool provides a graphical user interface and supports deploying plug-ins to a Microsoft Dynamics CRM 4.0 server. The source code for the application is provided to show you how to use lower-level plug-in registration classes. For a detailed description of how to register and deploy a plug-in by using the tool, see Plug-in Walkthroughs.

The other tool is a console application called PluginDeveloper. The source code for the tool uses the higher-level RegisterSolution message and related SDK classes to register plug-ins. For more information about RegisterSolution, see Registering Plug-ins Programmatically.

Either tool can be added to the Visual Studio Tools menu as an external tool to speed up the development process.

Note    The plug-in registration tools are provided as example solutions for registering plug-ins. By using the plug-in registration classes, you can write code to customize the way your plug-ins are deployed. For source code that shows you how to use the low-level registration classes, see the SDK\Server\FullSample\PluginInstaller folder or the SDK\Tools\PluginRegistration folder of the SDK samples.

Plug-in Storage

Plug-ins can be deployed to the Microsoft Dynamics CRM server's database or the file system that is known as "on-disk". We strongly recommend that you deploy your plug-ins in the Microsoft Dynamics CRM database, instead of on-disk, as the primary way to deploy plug-ins for Microsoft Dynamics CRM. Plug-ins stored in the database are automatically distributed across multiple Microsoft Dynamics CRM servers in a datacenter cluster. On-disk deployment of plug-ins is supported for backward compatibility with Microsoft Dynamics CRM 3.0 callouts and also to support debugging of plug-ins by using Visual Studio 2005.

Deployment

When you deploy plug-ins from another computer to the Microsoft Dynamics CRM server disk (on-disk deployment), the plug-in assembly must be copied to the server before registration. The assembly must be deployed to the following folder. This is the same folder that is used for Microsoft Dynamics CRM 3.0 callout assemblies.

<installdir>\Program Files\Microsoft CRM\server\bin\assembly

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 CRM 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.

A plug-in can be composed of more than one assembly. Plug-ins can be a collection of files that includes other referenced assemblies and configuration files. 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 (GAC) on each server where the plug-in is to execute.

Before you unregister an asynchronous plug-in, stop the asynchronous service. Failure to do this can result in a situation where the plug-in has been queued to execute, but the plug-in assembly is no longer available.

Security Restrictions

There is a security restriction that enables only privileged users to register plug-ins. 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.

Note 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

The System Administrator and System Customizer roles have these privileges.

See Also

Concepts

Tasks


© 2010 Microsoft Corporation. All rights reserved.


Show: