Plugins in Dynamics 365

Microsoft Dynamics 365 provides many great out of the box (OOB) features. Nevertheless, many business scenarios demand enhancements to the OOB system that require implementing customized logic. This customization can be done in various ways, including Java Script, Custom Workflows, Custom Reporting, Scheduling Jobs, writing Plugins, etc.

Plugins are probably the most common and are a favorite among developers when it comes to implementing customized logic around entity actions (Create, Update, Delete, Associate, and Disassociate). A plugin is a class library that can be written in .Net platform-supported languages, including C# and Visual Basic. Class libraries – which are compiled into a DLL file (and more than one plugin can be part of a single DLL file – must be registered in the Dynamics 365 environment. Customized logic in plugins integrates with Dynamics 365 to perform desired business processes. In today’s blog, we’ll show you how that works…

Step 1: Getting Ready

First, we need an IDE to get started with plugin development. If you don’t already have them, download a Visual Studio and .Net Framework from Microsoft’s official website. The most recent version of Dynamics 365 can only support customized code built with Framework version 4.5.2 or later.

Next, if you don’t already have it, it’s time to Install Microsoft Dynamics 365 Customer Engagement Developer Guide (previously known as CRM SDK). As of Dynamics 365 v9, there is no longer a Microsoft-provided download for the Software Development Kit (SDK). However, by using either PowerShell or NuGet, we can still install the developer tools, assemblies, and code samples that are shipped as part of the SDK for Dynamics 365 v9.

Step 2: Writing a Plugin

We need a placeholder for our customized code, so choose a development language and then create a new Solution and Project in Visual Studio. Note that we cannot generate an executable file without having a Project and Solution.

Next add a “Class” and specify a class name for the plugin. This is where we would write a code to implement a business logic. Extend the class from Microsoft.Xrm.Sdk.IPlugin.

The SDK assemblies are available as NuGet packages that you can directly use in your Visual Studio projects. For information about using a NuGet package in Visual Studio, see Install and use a package in Visual Studio.

In the Create Strong Name Key box, enter a file name. Note that we will not be able to register our plugin to Dynamics 365 without having the Strong Name Key (SNK) created. SNK is system oriented, and when you move this development code on another machine, SNK needs to create again.

Everything is now set, so we are ready to implement business logic.

Step 3: Plugin Registration

The following developer tools in the SDK are available as NuGet packages:

To download developer tools, see Download tools from NuGet.

To register the plugin with Dynamics 365, we can use the Plugin Registration Tool. Enter all required connection information to establish a connection with the target Dynamics 365 organization. While registering new plugin step, we select PrimaryEntity and the Message actions (Create, Update, Delete, Associate, and Disassociate) for the plugin that is being Created/Updated.

Step 4: Pipeline Events

The next important attribute is Pipeline Stage, where we determine on which stage the plugin will fire. There are two main categories in which the event processes: Asynchronous (process runs in the background) and Synchronous (process runs immediately).

Step 5: Debug a Plugin

If implemented logic isn’t working as expected, we need to debug our code to identify the problem area and then reregister the plugin after fixing the code.

We can do this a few different ways, depending on whether you have an On-premises or Online instance of Dynamics 365.

Select the plugin and then click on the Start Profiling option from the menu. Make necessary setting changes in the Profile Settings window. Choose Exception (Recommended) option and you will see an exception/error upon performing steps that we want to test. We can save thrown exception in the form of log file, which will be used to debug code. Choose Persist to Entity option to generate and profile in Dynamics 365 without throwing error. Later, we can use generated profile to debug code.

Once you have log file or profile created, open plugin code in Visual studio. Navigate to Debug menu and select Attach to Process to add PluginRegistration.exe that establishes the connection between code and Plugin Registration Tool. Don’t forget to add breakpoints to the key areas of code we want to test.

Go back to Plugin Registration Tool and select Plugin to test. Click Debug from the menu, select generated log file, and select the most recent .dll of the plugin we are testing. Click Start Execution and you will see debug triggered. Please refer to our detailed blog on Plugin Debugging for more information.

Do More with Dynamics 365: Expand your knowledge of Dynamics 365 through PowerObjects’ educational blogs.  Looking to learn in a more formal setting?  Check out our in-person training courses.

And that’s it! Happy Dynamics 365’ing!

Q & A: Dynamics CRM and NuGet

If you've done any custom .NET development against Dynamics CRM you've undoubtedly downloaded the Dynamics CRM SDK and run a few of the samples to get a feel for how things work. You've probably also noticed that all the .NET samples use one or more assemblies that ship with the SDK to make things work. If you're developing against CRM 2011 or 2013 and haven't moved things around, all the samples should just work as all the project references are already set to point to the assemblies in the SDK's bin folder. In CRM 2015 this has changed, instead of using that fixed path the samples are now configured to use NuGet as the source of the required assemblies.

Question: So what is NuGet?

Answer: Basically it's a central, web based repository that provides a quick and easy way to share packages of files that can be included in development projects. Now with this change when you build one of the SDK sample projects if the assemblies aren't present in the project they will be downloaded automatically.

Question: What is the benefit?

Answer: One major benefit is that you no longer need to rely on a specific path to a file being present. A common problem that surfaces in multi-developer environments is that each developer has their SDK assemblies downloaded to a different location. When the first developer creates a project and adds an assembly reference it uses the path to the file on their local machine. When another developer checks the project out of source control, the project is still looking for that same path when it starts to look for all the referenced files. Inevitably this will fail and the references will need to be fixed, which then presents the same problem back to the original developer when they get the latest version. With NuGet files are downloaded directly to each user's project folder.

Question: What is required to use NuGet?

Answer: Support for NuGet comes in the form of a Visual Studio extension and is available for Visual Studio 2010 and later.

Question: What versions of CRM assemblies are stored on NuGet and how do I get them?

Answer: Starting with the last 2 releases of the CRM 2011 assemblies all subsequent releases of CRM 2013/SP1 and 2015 are present. The assemblies are broken into 3 separate packages depending on your needs:

Core Assemblies – Microsoft.Xrm.Sdk & Microsoft.Crm.Sdk.Proxy

Workflow Assembly – Microsoft.Xrm.Sdk.Workflow

Client and Portal Assemblies – Microsoft.Xrm.Client & Microsoft.Xrm.Portal

You can use the Package Manager Dialog in Visual Studio to browse for a particular package or you can quickly use the Package Manager Console to target a specific version. If you use the Package Manager Dialog approach you'll need to do a little searching to find what you need but as a reward you'll have the benefit of being able to select which project(s) the package should be applied to.

Dynamics CRM and NuGet

If you go the Package Manager Console route you can look up the specific version you want to install from the NuGet site and then target a specific project with a single command. If you don't specify a version you'll end up with the latest version available which is currently CRM 2015 and if you don't specify a project it will be applied to all of them in your solution.

Dynamics CRM and NuGet

Not into coding? Check out these tips to use some of Dynamics CRM's built in functionality to achieve amazing things!

Happy CRM'ing!

Using Canary and Plugin Trace Viewer to Track Down Performance Issues

A common request we hear is to do a review of Dynamics 365 customizations to ensure they are working as efficiently as possible. An example of this would be if end users see opportunity product saves that take 30+ seconds or sporadic errors from JavaScript and plugins.

In the past, this meant adding trace code through all the plugins for which we had source code, and then figuring out which were triggered by the actual event and which were triggered because of the initial plugin. As you can imagine this would be a daunting task with code you know very little about. Fortunately, there are two tools that can help speed up this process!

The first tool is called Canary. Canary is a solution created by Jonas Rapp that you import into CRM that will dump the IPluginExecutionContext in an easy to read format. Out of the box, Canary has a post-step setup for Updates as well as PreValidation steps for all entities including: Create, Update, Delete, Assign, Associate, Disassociate, Execute, GrantAccess, RevokeAccess, Merge, Lose, QualifyLead, PickFromQueue, Route, SetState, SetStateDynamicEntity, and Retrieve.

You can add other steps as needed to help trace down any other issues you may run into. If you add ParentContext=true to the unsecured configuration of the plugin step, this will dump out all the parent context information. This is extremely helpful when trying to track down a recursive plugin call. For example, if there is a plugin that fires on the update of a quote to update the associated quotedetail records, and the quotedetail also has a plugin to push data back up to the parent quote.

plugin trace viewer

The second tool is the Plugin Trace Viewer that is available in the Plugin Store of the XrmToolBox. This tool takes the mountain of data that can be in the CRM Plugin Trace Logs and places it in an easy to read format. It has the option of turning on all tracing, just exceptions, or turning off tracing in CRM. As you can see in the screenshot below, the results are grouped together by the correlation ID which allows you to see the entire set of plugins that were called from one operation in CRM.

plugin trace viewer

The Plugin Trace Viewer has a pane for both the Trace Messages and any exceptions encountered during execution. The tool also allows you to filter the results by date range, plugin, message, entity, and/or the correlation id.

These two powerful tools will have you well on your way to tracking down many of the common problems we see in plugin code. You can download the Canary Solution from GitHub here. The Plugin Trace Viewer is best used in the XrmToolBox, which includes many other tools to help speed up the CRM development process.

For more tips and tricks, subscribe to our blog!

Happy Dynamics 365'ing!

Plugin Unsecure Configurations Made Easy

One of the more common use cases in Microsoft Dynamics 365 tends to be writing plugins and needing to pass parameters that the plugin code can use.

The traditional format to pass parameters has been XML that is pasted in the unsecure configuration. Parsing XML tends to be cumbersome and one ends up writing more code and spends more time maintaining that code rather than focusing on the business logic within the plugin. The question is: can we do any better?

Yes, there is a better way! The following process is what we tend to use to simplify this task:

Step 1

Build a class that contains the variables that you want to pass in through the unsecure configuration.

For the purposes of our example, our class definition looks like the screenshot below.

plugin

Step 2

Instantiate the object and serialize it. You could use JSON.NET or write your own. In either case, the serialized output will be similar to below.

plugin

Step 3

Paste the JSON in the unsecure config of your plugin step.

plugin

Step 4

In your plugin code, deserialize the JSON as follows

Code for the Deserialize method is below.

plugin

Sample code for the JsonHelper class was derived from this Microsoft article.

Step 5

Now you are free to use variables defined within the reserialized object as you need in your plugin code. Mission accomplished!

For additional information, check out the following blogs:

Comparison: Using Workflows vs. JavaScript vs. Plugins in Dynamics 365

Setting Output Parameters in Plugins for Custom Actions

Happy Dynamics 365'ing!