Much has been said about upgrading Sitecore solutions with the two main approaches being:

  1. Create a vanilla instance of your target Sitecore version and use packages or a tool like Razl to migrate content to this instance. Doing this you accept the risk that the migrated items may not contain some metadata that is essential to the target version and would normally be setup during the upgrade process.
  2. Follow the upgrade steps and go through the nightmare that are web.config changes and partial file installs (the upgrade wizard doesn't always overwrite old files).

In this blog post I want to discuss another technique that will make your upgrades a little easier and solve some of the above problems. This is based on carrying out 3 Sitecore upgrades in the last two months.

Lets first identify the main aims of upgrading:

  1. Upgrade the configuration
  2. Upgrade the code
  3. Upgrade the databases

So how do we get there?

Step 1 - Lists

Create a list of all the Sitecore version you are currently using and all the modules that you have installed. 

Step 2 - Download Vanilla

I am not talking about downloading Vanilla Ice's greatest tune:

Download vanilla versions of everything you listed in Step 1 from SDN. 

Once you have downloaded everything create yourself a clean install of Sitecore with all the additional modules. You should now have a vanilla Sitecore instance that DOES NOT contain any of your custom code or items

Step 3 - Config Hell

This step is the most painful! Using the vanilla instance created in Step 2 compare your project configs to the vanilla configs (use WinMerge) and extract any customisations into a transform file or Sitecore config include file. This will take you some time but once complete you will have clean configuration files in your project.

Step 4 - Upgrade The Databases

We now need to upgrade our databases to our target versions. Start by updating the connection strings for your Vanilla site in Step 2 to point at your databases that contain your site data. You should now have you Vanilla site pointing at your content. 

Follow the upgrade steps for Sitecore and each of the modules using your Vanilla site. With the Vanilla site all we are interested in doing is upgrading the database, we aren't worried about the file system.

As part of the Sitecore upgrade you will need to update the config files in your vanilla site. To save yourself a lot of time just download the latest version of Sitecore at each step and drop the config files from the zip file into your project. No more manually trying to merge web.config changes.

After running each Update package check that any post installation steps have run. These tasks are the most important part because they are changing values and updating our Sitecore items. Sometimes these tasks won't run because the Update Installation Wizard hasn't installed a DLL correctly (this happens a lot with WFFM). If this happens open the update package and extract the DLLs into your bin folder, then run the update package again.

Once you complete this step you should have the Vanilla site upgraded to your target versions with your Sitecore databases upgraded.

Step 5 - Upgrade the Code

Using the assemblies from your target Sitecore version upgrade your code. 

Step 6 - Upgrade the Config

In Step 3 you should have extracted any config changes into a separate transform files or Sitecore includes, therefore it should be a simple task to drop in the new configs into your project.

Step 7 - Build another Vanilla Site

You should now have your databases, code and configs upgraded to your target version, but before you deploy to live you need to build one more vanilla site. 

We have to do this because the Sitecore Update Installation Wizard doesn't always correctly write new files to disk. I am not entirely sure why this happens but looking at the logging it seems that the Update Installation Wizard tries to check the older file version and then makes a decision about replacing it. If the old file is different to what it thinks it should be then it doesn't overwrite the old file.

To resolve this we create a new vanilla site using the target version of Sitecore and all the modules. Once you have created your vanilla site change the connection strings to point at your upgraded databases with your content and then deploy your code on top of it.

Step 8 - Sit back and relax.

You have now completed the upgrade, it is time to relax and let your testers play with the site.


The main advantage of this route is the DB upgrade using the Vanilla site for the following reasons:

  • If at any point one of the steps fails to install files correctly you can grab the correct files easily from SDN. 
  • The process is quicker because the vanilla site does not contain any of your customisations. 
  • You don't waste time by trying to merge each setup of config changes.
  • You have extracted any customisation to the config so the next upgrade should be even easier.

Let me know what  you think of this route and if it works for you.

Glass needs your support!

Glass.Mappper.Sc is supported by the generous donations of the Glass.Mapper.Sc community! Their donations help fund the time, effort and hosting for the project.

These supporters are AMAZING and a huge thank you to all of you. You can find our list of supporters on the Rockstars page.

If you use Glass.Mapper.Sc and find it useful please consider supporting the project. Not only will you help the project but you could also get a discount on the Glass.Mapper.Sc training and join the Rockstars page.

Become a Rockstar