External assemblies in Dynamics CRM plugins with ILMerge

A requirement that has been around since Microsoft Dynamics CRM 4 is the capability of using functionality from external assemblies in plugins. A very common example of this is using Newtonsoft.Json dll to convert REST data to Type Objects.

Now, with CRM 4 On premise there was a classic approach used by many developers. You simply added the Newtonsoft.Json assembly in the server\bin\assembly folder of your Dynamics CRM installation and CRM would automatically pick up the assemby.

While this way of working was supported and works rather well for an On Premise environment, it has become quite outdated.
One of the main reasons is that when using a CRM Online we simply can’t put any assemblies in that folder anymore.

So how do we add external assemblies in a CRM Online environment?

[bra_divider height=’5′]

Using IL Merge to add external assemblies

A proper solution to the problem above is to use ILMerge and merge the two assemblies into one assembly. Microsoft describes the functionality of ILMerge as follows.

ILMerge is a utility for merging multiple .NET assemblies into a single .NET assembly. It works on executables and DLLs alike and comes with several options for controlling the processing and format of the output.

[bra_divider height=’0′]

While this functionality is exactly what we need, it can be quite a pain in the *** to properly merge the assemblies if you’re not really comfortable with ILMerge. Luckily for us even that has changed now.

[bra_divider height=’5′]

Well hello NuGet

One of the greatest things about NuGet is that developers share their problem-solving packages. One of those packages is the MSBuild ILMerge task. This package takes away all hastle that usually comes with merging assemblies…. here’s how it works:

MSBuild ILMerge automatically merges all referenced assemblies that are set to CopyLocal=true in your building assembly.

Yes, you’ve read that right. Automatically. You don’t even have to configure anything, just install the Nuget Package and build your plugin-project! However there is one caveat. When referencing the CRM assemblies, the following assemblies have the Copy Local property set to true by default.

Microsoft.Xrm.Sdk.dll

Microsoft.Crm.Sdk.Proxy.dll

Microsoft.IdentityModel.dll

Be sure to change these assembly properties and set Copy Local to False. If you do not change these settings, ILMerge will include them in your assembly and it will most likely crash your CRM environment.

[bra_divider height=’5′]

A short walkthrough

It should be pretty self-explanatory so I’ll keep the walkthrough brief.

Open up your CRM Plugin Solution

Reference the required assemblies, preferably using Nuget.

Install the MSBuild IlMerge Nuget Package with the following command:

Install-Package MSBuild.ILMerge.Task

Verify that the Microsoft assemblies have Copy Local set to true as explained above.

Finally build your poject.

Open up your dll with ILSpy or JustDecompile and you’ll see that your dll contains the merged assemblies.

That’s it for today, I hope it helped you!

** Disclaimer: Microsoft mentions in their blogpost that the use of ILMerge is unsupported. The method described above is thefore not supported by Microsoft and should be used with caution.**

Let's thrive together

Thrives is not just our company name. It’s our goal for everyone involved in the process of delivering the best possible solution and experience from employees to customers. By leveraging the best in people, the Dynamics 365 Customer Engagement and Power Platform.