Registering the plugin
Microsoft provides a plugin registration tool as part of the SDK. This tool is located in the SDK\Tools\PluginRegistration folder of the SDK. Prior to running the plugin registration tool, copy the Chapter3-DynamicsCRM.AcctPlugin.dll to the <installation directory>\Program Files\Microsoft CRM\server\bin\assembly
on the servers where Dynamics CRM resides. You need to put the assembly
here if you want to debug it later or if you are not using the database
storage option. If you do choose to store the plugin assembly in the
Dynamics CRM database and are not concerned about debugging your plugin,
then the assembly may reside anywhere during registration:
The
plugin registration tool is included in the Dynamics CRM SDK as an
example application. Go to the location where we unpacked the SDK and
navigate to the tools\pluginregistration folder. Build the project and launch the executable.
Connect to the Dynamics CRM 2011 instance.
Click the option to register a new assembly:
Navigate to the Chapter3-DynamicsCRM.AcctPlugin.dll assembly and click Load Assembly.
Specify the Isolation Mode as None. There is an additional option of Sandbox
that introduces a series of limitations on plugins run in that mode.
Sandboxed plugins have limits on access to the file system, Event Log,
network, and more. This is a very useful option when offering a hosting
environment, as a provider can restrict the types of plugins that each
customer in the shared environment can deploy.
Next, choose the location to store the plugin. The default option is Database but we may also store the file on disk or the Global Assembly Cache. Set the location as Database.
Click the Registered Selected Plugins button&; to load and register the plugin in the Dynamics CRM database:
Next up, within the Registered Plugins & Custom Workflow Activities window, select our new plugin, and choose Register and then Register New Step from the menu.
This window lets us register the event and entity that should trigger our plugin. Set the event, called a message in Dynamics CRM, to Update. There are many message options, including Create, Close, Merge, Retrieve, and more.
Set the Primary Entity value to account. This is the entity whose message will launch the plugin. Note that by using the Filtering Attributes property, we can set which fields on an entity trigger the message.
Set the Eventing Pipeline Stage of Execution to Post-operation.
Plugins run within the execution pipeline of entity processing. Plugins
that run in the "pre" stage operate before the message is saved to
Dynamics CRM. It is a useful place for doing data validation. The "post"
stage is a good place for logic that should run after the data is
committed to Dynamics CRM. In our case, we want to send the message to
BizTalk Server after the entity has been updated. Select the radio
button next to Post-operation.
Finally,
set the execution mode. Plugins can run either synchronously or
asynchronously. A plugin that validates data before saving it should run
synchronously so that the user can be notified if any errors are
encountered. In this case, our service should execute after the Dynamics
CRM user has finished updating the entity and we do not want to
interrupt or delay the user while the BizTalk service is called. Set the
Execution Mode to Asynchronous:
With
the step registered, our last step is to register an Image. Recall that
the Update message only contains the fields that have undergone a
change. If we need to access other fields from the entity, we either
have to invoke the Dynamics CRM services, or, even better, use an Image
that gets passed into the plugin. Select the plugin from the Registered Plugins & Custom Workflow Activities window, select the Register, and then the Register New Image button.
Set the Image Type as Post Image, and set the Name and Entity Alias to PostEventImage. The Parameters setting allows us to set which fields on the entity we want available in the Image. Leave this value as All Attributes. Finally, click theRegister Image button.
At this point, our configuration should look like this:
We have now successfully built a Dynamics CRM 2011
plugin and registered it with the system. This plugin will
asynchronously fire after an account record has been saved and pass a
complete image within the IPluginExecutionContext object.
Testing the plugin
To test this configuration, we simply need to change
the details on a specific account. Because we registered this plugin to
fire on any change to an account entity (vs. filtering which attributes launch the plugin), any changed attribute will do:
Open Dynamics CRM 2011 and navigate to the Accounts view.
Open any existing account to view its attributes.
Change
any one attribute of the account. In the example above, I changed the
account number from 10094 to 10095. The plugin should launch nearly
immediately. Check the Event Log of the machine hosting Dynamics CRM
2011 and watch for the events signifying success.
Next,
switch to the folder that BizTalk Server sends the account change
events to and confirm that the event was published there.
