Chapter 25. Plug-ins

A plug-in is a .NET assembly that can be used to intercept events generated from the CRM system to perform a variety of actions. An example of event interception is an entity that will be created, updated, or deleted; and an action can be almost anything. Some common plug-in uses include the following:

Performing a complicated update routine on CRM entities/attributes when it might be impractical to use JavaScript or business rules

Grabbing data from another system and updating CRM when an entity instance is being created or updated

Updating another system programmatically from CRM (such as an accounting system)

Figure 25.1 shows the event execution pipeline order in which the event and the plug-in calls are executed.

Developing plug-ins in sandbox mode is the recommended action, because it makes them more secure and supported on all the CRM 2016 deployment types (Online and On-Premises). They are also monitored by the CRM system-generated runtime statistics that can be queried using the PluginTypeStatistic entity records. If the sandbox worker process exceeds threshold CPU and memory limits and becomes unresponsive, the system kills it. In this case, currently executing plug-ins fail, but upon the next engagement, the plug-ins execute normally.

Finally, to deploy a plug-in without isolation mode, you need to add it as a deployment administrator, via the CRM Deployment Manager. Failure to do so results in failure to deploy the plug-in.

Asynchronous mode releases the application process, and the user can continue working while the code is executed. You can check the execution status of asynchronous plug-ins from Settings > System Jobs. These plug-ins are executed by the Microsoft Dynamics CRM Asynchronous Processing Service, which is a Windows service.

Pre-Stage—This stage is divided into pre-validation and pre-operation and sends control to the plug-in before the real event is executed in the core system. For example, you might attach a plug-in to the Create event of the Account entity; your code would execute before the Account was actually created in the CRM system. With this method, you could prevent the account or the entity record from being created.

Post-Stage—This stage is executed after the real event has executed in the core system. So, following the example just described, your code would be executed only after the account record has been created.

Dynamics CRM 2016 allows these stages to participate in SQL transactions as well.

The concept of using transactions now allows the rollback of a plug-in operation. If you have two different plug-ins attached to the same message of an entity and the second plug-in fails, it can now roll back the successful operation performed by the first plug-in. This was not easily done with earlier versions of Dynamics CRM. You can check whether a plug-in is running in a transaction by checking the IsInTransaction property of IPluginExecutionContext. The stages 20 (pre-operation) and 40 (post-operation) are the ones that guarantee to be part of a transaction, whereas stage 10 (pre-validation) might not be part of it.

Server—The plug-in executes on the server. Execution occurs when users use the web client or the Outlook Online client as well as when any workflow is executed.

Offline—The plug-in executes on the client user machine where Outlook is running. This is especially useful when you’re running the Outlook client in offline mode.

Both—The plug-in executes on the server and in the Outlook client in offline mode. Keep in mind that the plug-in is executed twice: once when Outlook is offline and again when it connects to the server.

The deployment type you select depends on what you want to do. If you need to grab data from an external system and need to have the user connected to the Internet or the network, you should have the plug-in run only on the server side, and the Outlook client will not have network access in offline mode.

Plug-ins are the best choice for enforcing complex business rules of your business. You could use JavaScript events to add validation on the rules you want to enforce; however, those types of validations work only when CRM is used through the native interfaces (such as the web or Outlook client). If you remember that other applications can be interacting with the CRM system through the web services, service endpoints, and so on, the validations and rules enforcement will work always if you put them on plug-ins or business rules. Plug-ins run on the server side, whereas JavaScript validations run on the client side. It is a good practice to put the validation logic in one place on the server side; that way, you know the hardware and resources you can use. Clients have a lot of different setting configurations on their browsers, and in some cases they might cause your validations to not work properly.

For more information about business rules, refer to CHAPTER 22 “Customizing the System.”

Download the MicrosoftDynamicsCRM2016SDK.exe file, save it, and execute it (it is a self-Eetracting cabinet file) by double-clicking the file and entering the directory where you want to extract the files (see Figure 25.2).

To create a plug-in, you must create a new class library project in Visual Studio, using .NET 4.5.2, by selecting File > New > Project. Then select Visual C# > Windows on the left and select Class Library in the middle. Enter a name for the project and select a location and a solution name if they don’t auto-populate when you enter the project name (see Figure 25.3).

The project template creates a new public class by default. After you create the project, you must add to your project a reference to the Microsoft.Xrm.Sdk.dll file and a reference to Microsoft.Crm.Sdk.Proxy.dll. These dynamic link library (DLL) files are located inside the SDKin subfolder.

To add these references, follow these steps:

1. Go to the Solution Explorer and right-click myPlugin > References (under the root Solution node of the tree). Select Add Reference, as shown in Figure 25.4.

2. Click Browse.

3. Locate the SDKBin folder on your local drive and select both the Microsoft.Xrm.Sdk.dll and Microsoft.Crm.Sdk.Proxy.dll files (see Figure 25.5). (To select more than one file, hold down the Ctrl key while you click the files you want.)

4. Click Add and then click OK to add the references to your project. You can then see these files inside the References folder of your project in the Solution Explorer (see Figure 25.6).

5. Add the using sentence to the Microsoft.Xrm.Sdk namespace and implement the IPlugin interface, as shown in the following code (where you need to rename Class1 with the name of your plug-in):

Click here to view code image

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Microsoft.Xrm.Sdk;

namespace myPlugIn
{
    public class Class1 : IPlugin
    {

  }
}

As with any other interface, you must explicitly implement methods. In the case of the IPlugin interface, you must implement the Execute method, as shown in the following code:

Click here to view code image

namespace myPlugIn
{
    public class Class1 : IPlugin
    {
     public void Execute(IServiceProvider serviceProvider)
     {
          throw new NotImplementedException();
     }
    }
}

The following sections explain the main classes.

Click here to view code image

IPluginExecutionContext context =
(IPluginExecutionContext)serviceProvider.GetService(typeof(IPluginExecutionContext));

This main parameter has a method, GetService, that enables you to get other services from the service provider, such as the context of the organization and the context of the tracer service. This enables you to interact with the current CRM trace to add debugging information for the execution of your plug-in. to get an instance of the trace service, use the following code:

Click here to view code image

ITracingService tracingService =
(ITracingService)serviceProvider.GetService(typeof(ITracingService));

IPluginExecutionContext inherits from IExecutionContext, which is a more generic interface that is also implemented by other classes, such as the RemoteExecutionContext class used for Windows Azure integrations.

You can use this property for tracking and logging purposes, especially when you have more than one plug-in attached to the same event, to see whether the codes execute for the same event pipeline.

Click here to view code image

Entity entity = (Entity)context.InputParameters["Target"];

The type of the target input parameter depends on the message. For example, the delete message returns an EntityReference:

Click here to view code image

EntityReference entity = (EntityReference)context.InputParameters["Target"];

It is a good practice to verify the type of the target parameter, as follows:

Click here to view code image

if (context.InputParameters.Contains("Target") && context.InputParameters["Target"]
is Entity)
{
    Entity entity = (Entity)context.InputParameters["Target"];
}

Also, you must make sure the entity contains the attribute you are looking for. The entity returned in the target parameter will contain only the attributes that were modified or created, and not all the entity fields. For example, the following code attempts to change the name of the Account entity:

Click here to view code image

if (entity.Attributes.Contains("name"))
{
entity.Attributes["name"] = "updated name";
}
else
{
    entity.Attributes.Add("name", " new account name");
}

For example, if there is an update operation in the account record where the name was not changed, that field won’t be included in the target parameter. If for some reason you always need to know the value of this field, you can register an image for your plug-in. See the “Images” section, later in this chapter.

Click here to view code image

Assign
Create
Delete
GrantAccess
ModifyAccess
Retrieve
RetrieveMultiple
RetrieveSharesPrincipalsAndAccess
RevokeAccess
SetStateDynamicEntity
Update

System entities can support other system messages. Refer to the message-entity support for plug-ins.xlsx file in the CRM SDK for a complete list of System entity–supported messages.

0 = synchronous and 1 = asynchronous.

Click here to view code image

Guid myAccountID = (Guid)context.OutputParameters["id"];

Click here to view code image

Guid id = context.PrimaryEntityId;

10 = pre-validation

20 = pre-operation

40 = post-operation

The service instance returned by IOrganizationServiceFactory has the method CreateOrganizationService, which is used get an instance of IOrganizationService.

Here is an example of how to use IOrganizationService and the CreateOrganizationService method:

Click here to view code image

namespace myPlugIn
{
    public class Class1 : IPlugin
    {
       public void Execute(IServiceProvider serviceProvider)
       {

          IPluginExecutionContext context = (IPluginExecutionContext)
serviceProvider.GetService(typeof(IPluginExecutionContext));

          IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)
serviceProvider.GetService(typeof(IOrganizationServiceFactory));

          IOrganizationService service = serviceFactory.CreateOrganizationService
(context.UserId);
        }
    }
}

The service instance returned by IOrganizationService has the following methods:

Associate—Used to create a link between records.

Create—Used to create records.

Delete—Used to delete records.

Disassociate—Used to remove a link between records.

Execute—Used, for example, to execute Fetch queries.

Retrieve—Used to retrieve a record.

RetrieveMultiple—Used to retrieve more than one record.

Update—Used to update records.

For more information about how to use this service and its methods, refer to CHAPTER 23.

Here is an example of how to use ITracingService and the Trace method:

Click here to view code image

namespace myPlugIn
{
    public class Class1 : IPlugin
    {
       public void Execute(IServiceProvider serviceProvider)
       {
          ITracingService myTracingService =
            (ITracingService)serviceProvider.GetService(typeof(ITracingService));
          try
          {
              // do your work
             myTracingService.Trace("Plug-in execution starts");
         }
         catch (Exception ex)
         {
             myTracingService.Trace("Plug-in Exception: {0}", ex.ToString());
             throw;
         }
       }
    }
}

The first step in plug-in deployment involves registering your plug-in and signing the assembly with a strong name key file. A strong name key is necessary for security so that the assembly can be trusted to execute external code, such as when invoking a web service. To sign your assemblies, follow these steps:

1. In the Solution Explorer, right-click your project and select Properties (see Figure 25.7).

2. Go to the Signing tab and check the Sign the Assembly check box (see Figure 25.8).

3. Create a new strong name key file by selecting New from the drop-down, as shown in Figure 25.9.

4. Enter a name for the key file and, optionally (but recommended), enter a password to protect the strong name key (see Figure 25.10).

5. Click OK to close the dialog, and you see the newly created strong name key added to your project in the Solution Explorer (see Figure 25.11).

To deploy your plug-in, you need to register it. You can do this programmatically or using a tool that comes with the CRM SDK called the Plug-in Registration Tool. The Plug-in Registration Tool comes as an application and is located in the SDKToolsPluginRegistration folder.

1. In Visual Studio 2015, select Tools > External Tools (see Figure 25.12). The External Tools dialog, shown in Figure 25.13, appears.

2. Click the Add button and change the title to CRM Plug-in Registration (see Figure 25.14).

3. Click the ellipsis ... button next to the Command field and locate the PluginRegistration.exe application file, which you should find in the SDKToolsPluginRegistration folder (see Figure 25.15).

4. Click Open to close the dialog and click OK to close the External Tools dialog. In addition, change the initial directory to the directory where you have the Plug-in Registration Tool.

You can now run the Plug-in Registration Tool from Visual Studio 2015 by selecting Tools > CRM Plug-in Registration (see Figure 25.16).

The Plug-in Registration Tool has the option to use the credentials of the user you are already logged in as, so you don’t have to enter the username and password every time you run the tool. If you want to use a different user credential, you can uncheck the Use Default Credentials check box (refer to Figure 25.17) and enter a valid username, password, and domain.

The username and password must be valid Windows account credentials and for a valid Microsoft CRM user with administrative roles assigned, as well as deployment administrator rights that can be added through the CRM Deployment Manager. If the plug-in is going to be registered with the isolation mode set to Sandbox, the user doesn’t need to be a deployment administrator; in that case, the CRM system administrator role is enough.

After you enter these values, click Login to connect to the organization and then select the organization you want to connect with.

If you need to connect to another organization, you need to click Create New Connection again. Doing so does not disconnect you from the first organization you connected to before but does create another tab with the second organization name you selected (see Figure 25.18).

If you are connected successfully to the CRM organization, you see the Registered Plug-ins & Custom Workflow Activities page, as shown in Figure 25.18.

Follow these steps to complete the plug-in registration:

1. Build the Visual Studio solution project so you can register the generated DLL, and make sure to build the assembly signed with a strong key to avoid a build error. Then click the Register button and then click Register New Assembly. The Register New Assembly dialog, shown in Figure 25.19, opens.

2. Locate your assembly by clicking the ellipsis ... button near the top of the Register New Assembly dialog. Select Sandbox under Step 3. (Remember that the sandbox isolation mode is preferred when deploying to a CRM Online environment.) Select Database under Step 4 and be sure to select the class you want to register that appears on the list. Then click the Register Selected Plugins button. When the assembly is registered, a confirmation window appears, as shown in Figure 25.20.

3. Expand the assembly you registered to make sure your assembly was properly registered (see Figure 25.21).

4. Associate the assembly with an entity and an event by clicking the assembly you registered in the previous steps and selecting Register > Register New Step (see Figure 25.22).

5. To register a step (and select the entity and event), enter the message Create in the Message field and account in the Primary Entity field (see Figure 25.23).

6. Select the Pre-Operation option from the Event Pipeline Stage of Execution list and leave the other radio buttons set to their default values, as shown in Figure 25.23.

While registering a plug-in, you can store configuration information, using the Secure Configuration and Unsecure Configuration boxes, shown in Figure 25.23. You can store data in any format you want. You can retrieve this information in plug-in code by using a plug-in constructor:

Click here to view code image

public myPlugin()
public myPlugin(string unsecure)
public myPlugin(string unsecure, string secure)

The first string parameter contains unsecure information, and the second one contains secure information. Secure configuration is not accessible in plug-ins executing in offline mode. Secure configuration is good for passing sensitive data, such as a connection string that contains a username and password.

7. Click Register New Step to close this dialog box, and you see the new step registered (see Figure 25.24).

As you saw in Figure 25.19, you can deploy an assembly to either the local hard disk or the database server or to the GAC (Global Assembly Cache). The database is the recommended option for production environments that might be deployed on different servers, such as a load-balanced deployment. This way you don’t need to deploy the assembly on every server. The local hard disk option is the recommended option for debugging purposes.

Be sure to properly debug and test your plug-in before implementing it to a production environment. If a plug-in has an error, users cannot create accounts if you attached the plug-in to the account Create event and the pre-stage (see Figure 25.25).

SEE the “Plug-in Debugging” SECTION, later in this chapter, for help on debugging.

Filter or specifying the fields for which you want the plug-in to be fired is something you can do when you create a new step for the Update method (see Figure 25.26).

For example, if you want to compare the value of the Account Name field of the Account entity, instead of getting an instance of the IOrganizationServiceFactory to create IOrganizationService and perform a Retrieve method (which junior CRM developers sometimes do), you can just configure this field on a pre-image and read it directly from there without doing any web service call that will decrease the performance of the server.

You need to create images by using the Plug-in Registration Tool. To to so navigate to Register New Image as shown in Figure 25.27.

In the Register New Image Dialog that appears, set Image Type to be Pre Image or Post Image, enter a name for the image, enter an entity alias, and, in the Parameters field, select the attributes or fields you want the image to contain (see Figure 25.28). Click the Register Image button, and you see the image inside the plug-in (see Figure 25.29).

Click Yes to confirm the operation, and you see a success dialog, as shown in Figure 25.31.

Before trying either debugging method, you need to build your plug-in with debug mode and put the PDB (project database) file generated by the compiler in the following directory (assuming that you have the CRM server installed on C:Program FilesMicrosoft Dynamics CRM): C:Program FilesMicrosoft Dynamics CRMServerinassembly. This file is located in the output folder of your Visual Studio project, which is typically located at debugin.

Unfortunately, you must restart the IIS after copying the PDB file. You can do this via the command prompt by running the following command:

Iisreset

You can also restart the IIS by using a PowerShell command, like this:

Click here to view code image

Restart-Service W3SVC, WAS -force

You must attach the Visual Studio debugger to the w3wp.exe process, for example, to debug an online plug-in. To do that, select Debug > Attach to Process, as shown in Figure 25.33.

When the Attach to Process dialog appears, check the Show Processes from All Users check box and select the w3wp.exe process, as shown in Figure 25.34.

If you are using the remote debugger, you must change the qualifier name to the name of the computer where the CRM and the remote debugger are installed.

If the plug-in has been registered with sandbox isolation mode, you must attach to another process instead of the w3wp.exe process. The process that hosts the plug-ins on a sandbox is called Microsoft.Crm.Sandbox.HostService.exe.

Click the Attach button to start debugging the plug-in.

Assuming that you registered the plug-in and associated it to the Account entity on the Create event (as in the earlier example in this chapter), when you go to the CRM web application and try to create a new account, you are automatically switched to the Visual Studio 2015 application (see Figure 25.35) after you click the Save or Save and Close buttons on the Account form.

1. Open the Plug-in Registration Tool, connect to your organization, and click the Install Profiler button (see Figure 25.36).

2. When the Plug-in Profiler is installed successfully, make sure it exists under the assemblies (see Figure 25.37).

3. Select the plug-in step that you want to debug, and you see the Start Profiling button available in addition to the Debug button (see Figure 25.38).

4. Click the Start Profiling button, and the Profiler Settings dialog appears (see Figure 25.39). These profiling settings are good for most scenarios. Click OK.

5. Perform the steps in CRM so that the plug-in step you are profiling gets executed. The Business Process Error dialog box appears (see Figure 25.40).

6. Click the Download Log File button to save the ErrorDetails.txt file on your computer. This log file contains the profile that the Plug-in Profiler will use to play back execution. Open the plug-in solution in Visual Studio and go to Debug > Attach Process and select PluginRegistration.exe (see Figure 25.41). Set a breakpoint in the plug-in code.

7. Go back to the Plug-in Registration Tool and click the Reply Plug-in Execution button that is on the command bar or select the step you are profiling and click Debug. Select ErrorDetails.txt for the profile location (Step 1) and select the debug version of the plug-in assembly for the assembly location (Step 2) (see Figure 25.42).

You can optionally click the down arrow to download the profile execution log from the server (see Figure 25.43). You will have files there if you previously selected Persist to Entity in the profile settings when you started the Plug-in Profiler.

8. Click Start Execution, and debugging starts in Visual Studio.

AccountNumberPlugin—This sample creates a random account number when an account is created.

FollowupPlugin—This sample creates a Task activity when an account is created.

PreEventPlugin—This sample demonstrates the use of shared variables to send data through different plug-ins.

WebClientPlugin—This sample shows how to access a network resource in a sandboxed plug-in.

AdvancedPlugin—This sample shows how to use pre- and post-images, tracing, how to pass secure and unsecure information, and so on.

You can find the code for these samples in C#, within the SDK, in the sdksamplecodecsplug-ins folder.

You can download the SDK from the Microsoft website; search for “Dynamics CRM SDK.”

To learn more about working with solutions in Dynamics CRM 2016, refer to CHAPTER 22, “Customizing the System.”

When importing your plug-in solution to another CRM organization, make sure you check the check box Enable Any SDK Message Processing Steps Included in the Solution, or your plug-in won’t work (see Figure 25.45).

Be careful about using secured configurations in the plug-in SDK message processing steps registration. The secure configuration is encrypted with a specific organization key and might be different from one organization to another. You might need to update this secure configuration manually for each environment where you install your plug-in solution.