Once our code is ready, we need to register it to the CRM platform, so that it can execute on corresponding events. We can register our plug-in using SDK or we can use the plug-in registration tool that comes with CRM SDK. We can find this registration tool under the SDKToolsPluginRegistration location. We can run the PluginRegistration.exe file to register our plug-in.
Perform the following steps to set up a connection with the CRM server:
Once is it connected it will display the already registered assembly list, if any. Now we can register our plug-in. To register the plug-in we need to understand the concepts discussed in the following sections.
While registering a plug-in we have the option to register our plug-in in isolation mode, also known as sandbox mode, or none. Plug-ins registered in isolation mode run with limited resource access; they can't access file systems, the registry, certain protocols, and event log information. CRM Online only allows us to register plug-ins and custom workflows in isolation mode, so any plug-in or custom workflow registered on CRM Online can't use the preceding resources. But if required, we can use plug-ins and custom workflows for the integration. We can use custom Web services, deployed on a standard secured port (80 or 443), or on Microsoft Azure. Plug-ins registered in non-isolation mode don't have such restrictions and they make full use of resources.
During the plug-in registration we also need to specify assembly storage; we have three options for plug-in storage: Database, Disk, and GAC.
This is the recommended option for storing plug-in assembly. There are positive reasons for storing plug-ins in a database, such as recovery assembly; if the source code is damaged, we can get the assembly from the database. The benefit of storing assemblies in a database is that, when we are working on a multi server deployment, we don't need to keep our assembly in all the servers.
Note
You can refer to http://nishantrana.me/2011/01/17/get-the-plugin-assembly-stored-in-database-in-crm/for for more on how to get plug-in assemblies from the CRM database.
If you select the disk option for plug-in storage, you need to keep your assembly in the bin folder under CRM installation path: Serverin in CRM server. So if you are using multi server deployment, then you need to keep this in every CRM server.
If you select the GAC option, plug-in assembly should be registered in the Global Assembly Cache (GAC) of every CRM server.
Let's register our sample code using the following options:
- Click on the Register drop-down and select Register New Assembly.
- Click on the ellipse (…) under Step 1: and browse the sample plug-in assembly.
- Keep the other options at their defaults and click on the Register Selected Plugins button.
- Verify our assembly is available under the registered assemblies list:
Registered plug-in
Now our plug-in is registered in the CRM platform, the next thing we need to do is to bind our plug-in with a specific event. We need to register new steps, so let's first understand the options available for step registration.
Messages are the events that we need to use to trigger our plug-in—for example, create, update, delete, retrieve, retrievemultiple, and so on. As soon as you start typing the initial character it will show you the possible events available for plug-in registration. We will get all system events provided by the CRM platform and custom events that we can create using actions. We will be working on custom actions in a later topic.
Primary entity defines the source entity, if we want to trigger our plug-in on a specific entity on a specific message. So, for example, if we want to execute our business logic on an account entity record creation then our primary entity will be the account and the message will be create. But if you want to execute your business logic for all the entities, you can leave this field blank, so your message will trigger for all the entities. For example, if we register our plug-in on a retrieve message and don't specify the primary entity, it will run when any entity record is opened, but these types of scenario should be avoided because they can lead to performance issues.
This option is not used normally; we complete the secondary entity only when two entities are required for any message—for example, the SetRelated and RemoveRelated messages. The following is a list of the primary and secondary entities supported for SetRelated:
The Filtering Attribute is very useful to avoid running our business logic on unnecessary changes. Let's say we need to run some custom business logic when the annual revenue of the account is changed, then we need to register the updated plug-in on the account entity. If during the registering plug-in step All Attributes is selected, our plug-in will first update any account entity fields, but if we just select the annual revenue field under the filtering attribute, our plug-in will only update those specific fields. This option is also useful for avoiding infinite loops in update plug-ins.
This options allows us to set an impersonation option for our plug-in during registration. By default, plug-ins will be executing the security context of the calling user (who is responsible for the plug-in's execution), but we can impersonate our plug-in by selecting another user from this drop-down.
Every plug-in runs in a specific order. This option is used to specify the order of execution for the plug-in if we have multiple plug-ins registered on the same event.
In the event execution pipeline, we select the Pre-validation, Pre-operation, or Post-operation options. Please refer the earlier topic for the plug-in execution pipeline.
This option allows us to configure if we want to run our plug-in on the server or if we also want to configure it to run for the Outlook offline client. We can select one or both options depending on our requirements.
This option allows us to delete the record of the system job if our asynchronous plug-in is completed successfully.
Note
The system job entity is used to store information about asynchronous plug-ins, workflows, and other asynchronous operations by the CRM. You can get more details here: https://msdn.microsoft.com/en-us/library/gg328118.aspx.
