Authoring My First CRM Plug-in


Hello readers. Recently I’ve learned that building Microsoft Dynamics CRM is a much different beast from building on top of Microsoft Dynamics CRM. I’ve been on the team for a bit over 3 years, but just built my first plug-in. I’m not ready to tell you what it does but I wanted to share some insights I picked up along the way.

First off, the SDK documentation for Microsoft Dynamics CRM 2011 (now in beta) is good and continuing to be expanded. I remember trying to build some extensions three months ago, just to see how it worked, and I was constantly bugging my colleagues to explain the finer points – or sometimes the points at all. Now, thanks to the hard work of our SDK team, I can just pop open the help doc instead of distracting my peers. Don’t underestimate the power of great documentation.

clip_image002Second, I wish I had spent time understanding the entire model – including its surprises and dark corners – before beginning development. The particular “gotcha” that got me was the requirement that plug-ins intended for CRM Online must consist of only one assembly. (Actually, the requirement is a bit more complicated than that – what I’ve stated is the practical upshot for me, the newbie developer. See the end of the post for the full explanation.) I was trying to do the good software engineering thing by factoring my work into a library of core functionality and an interface layer. In fact, I built two interface layers: a console-based project for testing the library and the plug-in itself. Of course, because these were separate projects inside my Visual Studio solution, they compiled down to three separate assemblies.

Imagine my surprise when I registered the plug-in assembly and then couldn’t figure out how to register the other assembly. I dug into the SDK docs a little more, and there it was in black and white: only one assembly per plug-in if they’re going to run in CRM Online. In the beta SDK, the page title is “Register and Deploy Plug-ins”, in case you want to take a look yourself. Again, see below for the full explanation.

Fortunately, Bing saved the day, pointing me to the ILmerge tool. And that brings me to my third and final insight for this post: ILmerge is not trivial to get right under .Net 4.0. Further searching finally yielded some good results, so I’ll spare you that searching and just give you the command here. Imagine that your plug-in consists of two assemblies: PluginCoreLib.dll and PluginCrm.dll. Imagine both of these are in the same Visual Studio solution, but as separate projects. PluginCrm depends on functionality in PluginCoreLib, which means PluginCrm gets built last. You need to get both of these assemblies into a single deployable DLL which will be sent to your CRM server. After installing ILmerge, here is the post-build step you would set up inside the PluginCrm project:

"C:\Program Files (x86)\microsoft\ILMerge\ILMerge.exe" /targetplatform:v4,"c:\windows\Microsoft.NET\Framework64\v4.0.30319" /keyfile:"your-key-file.snk" /out:"$(TargetDir)PluginToDeploy.dll" "$(TargetDir)PluginCrm.dll" "$(TargetDir)PluginCoreLib.dll"

clip_image004You would then deploy PluginToDeploy.dll onto your CRM server. Of course, feel free to edit the name of the output DLL, and you certainly want to point to the correct .snk signing file. If you have other dependencies, you can add them after PluginCoreLib.dll.

I hope this post has helped you understand how to use ILmerge with CRM plug-ins, and that it’s encouraged you to read the fantastic documents before you dive into development.

Cheers,

Matt Cooper

Appendix 1: A fuller explanation of the single-assembly requirement.

Many thanks to Nirav Shah for his guidance and technical expertise here.

The requirement is that any plug-in assembly registered to run from the database must be in a single assembly, and all assemblies that run in the Sandbox must be registered in the database. CRM Online only allows assemblies to be registered in the Sandbox. Ergo, for CRM Online, the plug-in has to live in a single assembly. There are some technical challenges to registering multiple assemblies in the database that we haven’t had time to invest in working though. If you find this to be a blocker, let us know on http://connect.microsoft.com.

Appendix 2: Why ILmerge was unnecessary here.

Nirav also pointed out that since I wrote all the code, I could have used Visual Studio’s “Add as Link” option to make all the code end up in a single assembly. Ah well, this is why he’s a dev lead and I’m just a program manager =)

Comments (4)

  1. Ken says:

    First, I wish this had been published a few weeks ago 🙂

    Couple related comments from our experiments (and the related web search results) – If you are signing with a pfx instead of an snk file, and want to use ILMerge, you need to generate a .pub version of the pfx file for ILMerge to use, then resign the merged assembly with the pfx after merging.

    Also, isn't 'add as link' pretty much the same as using 'shared' code files at the source control layer?

    We are still leaning towards ILMerge just to avoid (when possible) having to change anything in the project itself when we deploy in sandbox vs. non-sandbox. Sandbox plugins would then just have the additional step of merging in our 'helper/framework' assembly containing our plug-in base class, shared utilities, etc. which end up being several code files we would have to 'add as link' in every sandbox plugin.

  2. Anne Stanton says:

    Nice Post!

    Anne

  3. Matt Cooper [msft] says:

    Hi Ken, hope it helped even if it was a bit tardy for your needs =)  Great tip on PFX files – I haven't ventured there yet myself.

  4. CRM Steve says:

    Nice post – and just when I was beginning to question the cloud!

Skip to main content