Developing and Testing Plug-ins in Dynamics 365 - Part 1

In this post I will introduce what a plug-in is, how to develop, deploy and test plug-ins.

Pre-Requisites

• Visual Studio 2017 Installed
• Admin Access to a Dynamics 365 instance

What is a Plug-in?

A plug-in is custom business logic (code) that you can integrate with Microsoft Dynamics 365 (online & on-premises) to modify or augment the standard behavior of the platform. Another way to think about plug-ins is that they are handlers for events fired by Microsoft Dynamics 365. You can subscribe, or register, a plug-in to a known set of events to have your code run when the event occurs.

So there we have it, it's definitely not the most user friendly name but it's here to stay, I guess better than callouts (Dynamics CRM 3.0 FTW)

1A. Tooling

In order to work with Plug-ins we will need to install the Plugin registration tool

1. Open Powershell
2. Navigate to the folder you want to install the tools to
3. Copy and paste the following PowerShell script into the PowerShell window and press Enter.

A Tools folder with four sub folders will be created:

• ConfigurationMigration
• CoreTools
• PackageDeployment
• PluginRegistration

The last one is the one we are interested in.

1B. Tooling

In order to be able to register plug-ins and do a large set of operations, we need to use the PluginRegistration tool

1. Open the tool from ..\Tools\PluginRegistration\PluginRegistration.exe
2. Click Create New Connection 
3. Tick Show Advanced
4. We enter user account details
• Online Region
• User Name
• Password
5. Click Login

The connections details will be saved so that next time they will be available.

2A. Project Preparation

A standard library (dll) project is needed for Plug-ins, additionally the project will need to be signed.

1. Create new Class Library (.NET Framework) Project called Plugins in Visual Studio and set Framework version to 4.5.2. 
2. Right Click Plugins project and go to Properties (Alt + Enter might work)
3. Click on Signing
4. Tick Sign the assembly
5. On the drop down, select <new>
6. Give the key a name and untick Protect my key file with a password
7. Click OK

2B. References

We are going to need some references to the SDK in order to create our first plugin

1. Right Click on References
2. Select Manage Nu-Get Packages
3. Click Browse
4. Search for Microsoft.CrmSdk.CoreAssemblies
5. Click Install to install Latest version (9.0.2.4 at the time of writing)

3. Development

The project is stored here and the plug-in code can be found here

The plug-in is really simple, it will set a search engine as the url for a new account if the first letter of the account name matches the first letter of a known search engine, empty otherwise.

We will register this in the pre-create operation so that it only fires on account creation.

One thing to note is that as the plug-in as it's currently written cannot be unit tested very easily or at all really. We will explore this in more detail on section 6.

4. Register Plug-in

Registering a plugin has two phases:

1. Register Library
2. Register Steps

The first step refers to installing the library on the server, while the seconds configures the events for which the plug-in will be triggered.

Start the Plugin Registration Tool

1. Click Register and then Register New Assembly


 
2. Select the plugins assembly (Plugins.dll) and click Register Selected Plugins



3. Locate Plugins Assembly, right Click and then select Register New Step



4. We fill in the details as shown below and Click on Register New Step

Note how the plug-in has been registered to trigger on the Create event (message in CRM parlance) of the account Entity and it will happen synchronously before the write operation. This is needed as the plug-in modifies the value of the entity and then the modified value is saved.

5. Test Plug-in

We create a record and save it. The website field is populated.

The problem is that the current solution is hard to unit test so let's try to improve that

6. Unit Testing

In order to make unit testing easier, we refactor the plug-in. The whole project can be found here and the changes can be found here.

Note how nothing really has changed, except that we can now easily unit test the plug-in, by extracting out the method.

The sole unit test is failing at this stage as we failed to take into account capitalisation when matching the first letter, hurrah for unit tests!!.

The fixed project is here and the fixed code is here.

The last comment I will make in this section is the Test Driven tests that I have used, see GetSearchEngineTest test method here.

This is a very powerful feature as it allows us to write a single unit test and then pass different inputs into it.

This is what it looks like on Test Explorer, which allows you to see which one is failing if any.

In part 2, we will look at how we can remove the hard-coded search engines to improve the code and also introduce more Dynamics 365 functionality