Skip to main content
Dynamics 365
·
3 min read

How to Reference Assemblies from Plug-ins

8/31/15This post has been edited to reflect that Dynamics CRM does not support ILMerge.  It isn’t blocked, but it isn’t supported, as an option for referencing custom assemblies.

You may have noticed that Microsoft Dynamics CRM 2011 (and CRM 4 before it) does not really have support for referencing custom assemblies from a plug-in assembly. You are limited to .NET Framework assemblies and the public Microsoft Dynamics CRM 2011 Software Development Kit (SDK) assemblies. In Microsoft Visual Studio, your references will look something like this:

clip_image002

If you wanted to reference an assembly that you had written, your options were pretty limited:

  • Register the assembly on disk with any referenced assemblies in the same directory.
  • Register the referenced assembly in the GAC
  • Include the relevant source code in the plug-in assembly

With the introduction of Solutions in Microsoft Dynamics CRM 2011, the first two options are not very manageable (as they require special setup on multiple servers during the installation of the solution). In addition, those options don’t work in Microsoft Dynamics CRM Online, since assemblies must be registered in the database in CRM Online. If you include source code, as the last option suggests, then all of the benefits of a referenced assembly are lost, without gaining any real benefits.

Merging Assemblies

Microsoft Research has published another tool that you may use for referencing custom assemblies (however, please note that it is not officially supported): ILMerge. It is a utility that merges multiple Microsoft .NET assemblies into a single assembly. Although this tool has been produced by Microsoft Research, it has been around since .NET 1.1 and is pretty stable. The newest version of the tool also works with .NET 4.0 (newest version of the CLR), which is how it impacts us. In order to get this example to work, you’ll need to use version 2.10.526.0 or above.

Suppose you created a library, PluginLibrary.dll, and wanted to add it as a reference in your plug-in assembly. If you are using ILMerge, you can do just that. Add a reference to your PluginLibrary.dll and build your project.

clip_image004

Once all of the assemblies have been built, ILMerge is run to merge them. Before we can start merging the assemblies, there are a few steps we need to take to get the tool to work with .NET 4.0. First, a config file (name it ILMerge.exe.config), as defined on the ILMerge web site. For convenience, here’s the file:

<?xml version=“1.0“?><configuration><startup useLegacyV2RuntimeActivationPolicy=“true“><requiredRuntime safemode=“true“ imageVersion=“v4.0.30319“ version=“v4.0.30319“/></startup></configuration>

If you are running ILMerge on a 64-bit machine, you’ll need to locate the 32-bit version of the .NET 4.0 assemblies. If you don’t do this, ILMerge will attempt to load the 64-bit assemblies. Since the tool is compiled as a 32-bit assembly it will throw a BadImageFormatException while loading a 64-bit assembly. On my machine, these assemblies are located at C:\Windows\Microsoft.NET\Framework\v4.0.30319.

As a side note, since ILMerge cannot load 32-bit assemblies while CRM 2011 requires 64-bit assemblies, plug-in assemblies must be compiled as platform neutral (can be loaded as a 32-bit or 64-bit assembly) in order to work with both ILMerge and CRM 2011.

Now that the environment has been prepared, let’s run the tool:

ilmerge /keyfile:PrivateKey.snk /target:library /copyattrs /targetplatform:v4,“C:\Windows\Microsoft.NET\Framework\v4.0.30319“/out:CompletePlugin.dll MyPlugin.dll PluginLibrary.dll

A quick explanation of the attributes:

– keyfile: Specifies the key file that should be used to sign the final assembly. An assembly must be signed in order to be registered with CRM 2011, so this is a required parameter.

– target: Indicates that the generated file should be a DLL

– copyattrs: Copies the assembly-level attributes from the assemblies and merges them. This is especially useful if you have included the generated entity classes (from CrmSvcUtil.exe) in your library assembly, as this will ensure that the assembly attribute, ProxyTypesAssemblyAttribute, is present on your merged assembly.

– targetplatform: The version of the .NET framework as well as the path to the assemblies. If you are running the tool on a 32-bit machine, the path is not required.

– out: Specifies the output DLL file name

– List of assemblies: The list of assemblies to be merged

Once the tool completes, the output assembly, CompletePlugin.dll, can be registered with Microsoft Dynamics CRM 2011.

Please note that the merged assembly cannot exceed the maximum assembly size (restricted by CRM 2011).

Links
  • ILMerge Web Page
  • Download ILMerge
365blog

Related posts