Registering Plug-ins Programmatically
[Applies to: Microsoft Dynamics CRM 4.0]
This section provides an overview of the messages and classes available in the SDK for plug-in registration. By using the provided information and code samples, you can develop custom programs to register your plug-ins with Microsoft Dynamics CRM. Source code samples of plug-in registration tools are provided in the SDK sample code in the SDK\Tools folder. Use the source code in these tools and the SDK documentation as a guide in developing your custom plug-in and custom workflow activity registration code. For more information about the tool sample code, see Sample Code.
Plug-ins are registered with the event execution pipeline to execute before or after a specific event occurs, in response to a specific message being processed, and for a particular business entity. Plug-in registration defines the run-time conditions under which the plug-in is to execute and the information that is to be passed to the plug-in. Because of the multitenant capability of Microsoft Dynamics CRM, a plug-in designed to work across multiple organizations must be registered with each organization's event execution pipeline.
For custom workflow activities, first create an instance of a pluginassembly for your custom workflow activity assembly. Next, create an instance of a plugintype for each custom workflow activity class in your assembly. Finally, set the PluginAssembly property of RegisterSolutionRequest and execute the request.
The RegisterSolution message is equivalent to a Create message and the UnregisterSolution message is equivalent to a Delete message. Notice that there is no support to update a registered plug-in. To update a plug-in you must first unregister the plug-in by using UnregisterSolution and then register it again by using RegisterSolution.
The pluginassembly class is used to define an assembly entity in Microsoft Dynamics CRM that contains one or more plug-ins or custom workflow activities. The pluginassembly entity contains information such as a user friendly name, the relevant organization, file name (pathname attribute), version, and other data. The pluginassembly instance is used to set the PluginAssembly property of the RegisterSolutionRequest instance.
The following restrictions apply when registering a plug-in assembly:
- You can register only one version of a plug-in assembly in the Microsoft Dynamics CRM database.
- To update the plug-in assembly to a new version, the old version must first be unregistered. It is recommended that you use UnRegisterSolutionRequest to unregister the assembly and all related plug-ins. Use RegisterSolutionRequest to register the new version of the plug-in assembly and any plug-ins within that assembly.
For more information about what values to assign to the PluginAssembly properties, see the SDK\Tools\PluginDeveloper code sample.
Step registration informs the Microsoft Dynamics CRM system about the conditions under which a plug-in is to be executed. It also defines what information is to be passed to the plug-in in the IPluginExecutionContext parameter of the IPlugin.Execute method. For more information, see the SdkMessageProcessingStepRegistration class.
Pre and Post Event Images
Images are snapshots of an entity's attributes at a given moment in time. The SdkMessageProcessingStepImageRegistration class identifies a named list of entity attributes whose values are to be made available at run time to the registered plug-in. A plug-in can access these images through the PreEntityImages and PostEntityImages properties of IPluginExecutionContext. Whether the image is obtained during the pre-event or post-event of the event execution pipeline depends on which stage the associated SdkMessageProcessingStepRegistration instance is being registered for.
An array of SdkMessageProcessingStepImageRegistration instances is used to set the Images property of SdkMessageProcessingStepRegistration.
Tip Registering for pre or post images to access entity attribute values results in improved plug-in performance as compared to obtaining entity attributes in plug-in code through Retrieve or RetrieveMultiple requests.
Note Only entity attributes that are set to a value or null are available in the pre or post entity images.
For source code that shows you how to register a plug-in, see the sample in the SDK\Tools\PluginDeveloper folder of the SDK samples. For source code that shows you how to register a custom workflow activity, see the sample in SDK\walkthroughs\workflow\cs\createlead\installer.
© 2010 Microsoft Corporation. All rights reserved.