Hardcore CRM: Do a major upgrade of a plugin version!

isclaimer / Warning / Attention:
This is not a task that you’ll conduct frequently. This task only makes sense if you are doing product  development in which you want to make an explicit difference between versions.
This procedure might wreck  your CRM solution…My warning didn’t scare you away?
Please, join in, buckle up! Time for some serious fun. At least you cannot say I didn’t warn you.

The last months I’ve been working on a large project. As with all projects, they do come to an end. Within the project we’ve had multiple releases, some big and some more small.
Today I had to make a delivery of the final product.This meant that I had to make a release with a major new version of the plugins within the solution.
A fairly large assembly with 45 plugins containing a total of 80 plugin steps and 62 registered images. Not a task for the faint hearted…

CRM has it’s own way of handling versioning of plugin assemblies. When you look at the standard .NET approach, a version number has four parts:

< major version > . < minor version > . < build number > . < revision >

As long as you don’t increment the major version, you don’t have to expect many problems when you update an assembly. Unfortunately Dynamics CRM works a bit differently. In case you change the minor version of the assembly, you can’t simply update your plugin in the plugin registration tool. You have to register the updated assembly as a new assembly and you end up with having two assemblies registered.

Too bad, the plugin steps and the associated images are still bound to the old version of the assembly. However there is a clever trick to bind all plugin steps to the new assembly. I’ll explain how. 

Step 1. Create a new “upgrade” solution

First of all within the solution manager in CRM, create a new solution. In this solution include the new and old assembly and include all SDK messaging steps that are being used by the old assembly.

The next step is to save and publish the new solution. Then export it as an unmanaged solution.

Step 2. Modify the customizations.xml

Just to be safe, make a copy of the exported unmanged solution. Just in case something goes wrong.
Then unzip the file and open the “Customizations.xml” file with you favourite text editor (e.g. Notepad ++).

In the customization file, you’ll find the registration of the new and old assembly AND (more importantly) the SdkMessageProcessingSteps which are bound to the old assembly.


Navigate to the XML section “SdkMessageProcessingSteps”.
In this section you will find all registered steps. As you can see each step is associated with a plugin type name. In our case it is bound to the old version

For every SdkMessageProcessingStep, you have to change the version number (in our case) to the new desired version number. Be careful don’t do a global search and replace.

Once done, save the file and close the editor.

Copy the modified customizations.xml back to the zip file.

Step 3. Import the “upgrade” solution

Import the modified “upgrade” solution. Once imported and published, both the new and old assembly have the plugin steps and images registered. The import process summary might show a number of warnings… you can ignore these. The system is now in a intermediate state.

What happened in the background is that all existing plugin steps and images  (that you exported) are now associated with the new plugin assembly.

Step 4. The great swap

In the actual solution (not the upgrade one, but the one you want to deliver), add the new assembly. You will see a list containing two assemblies. Remove the old assembly from the solution and publish the changes.

In the background the old assembly is removed from the project and the old plugin steps are gone as well. The “new” plugin steps remain.

Step 5. Wrap it up!

Once done, verify that your solution is still functioning.

  • If this is not the case, then you can import the copy of the unmanaged “upgrade” solution and start all over.
  • If this is the case: everything works like a charm. You can remove the old assembly from CRM and make a managed and unmanaged export of the actual solution.

Another job done!