Upgrading Sitecore CMS: A Better Way

St Lucia- Aug 2017

When I started with Sitecore in 2012 (v6.5) the base install consisted of 3 databases (Master, Web and Core) and a website root folder. It was relatively simple to drop the root folder somewhere on your machine, point IIS to it and create a site and finally attach the 3 databases to your sql server instance. A single config file update later (to set your connection strings) and Sitecore 6.5 was up and running. Whoops! Now copy in the license file and re-request on the browser.

At this point in my career with Sitecore, I can assure you that this isn’t how easy it was. In fact, it was a much longer trial and error approach to finally get to the login screen. Most of us who have worked with Sitecore over a longer period of time have all experienced the same challenges. My personal favorite is the thousands of times I’ve had to root cause an error only to discover that once again I forgot to publish template updates to the web database. All of this boils down to learning curve. Applying this learning curve to upgrades is no exception.

Sitecore Upgrades of [not so] Long Ago

When upgrading major versions, Sitecore defined an upgrade path that typically required engineers to apply multiple upgrade packages. Moving from 6.5 to 7.2 for example, required 3 upgrade packages transforming 6.5 to 7.0, 7.0 to 7.1 and 7.1 to 7.2. Arguably, the probability of successfully upgrading the first time remained relatively low.

The Upgrade Scenario

Sitecore upgrades consist of documentation (the upgrade guide), an update to Sitecore’s installation framework and one of more upgrade packages. In addition, there are typically SQL scripts to run on one or more of the databases.

The upgrade documentation is best described as a flowchart with a series of decisions, all written in plain language but lacking the flowchart diagram. In other words, read the documentation thoroughly then read it twice more. Once you’ve accomplished that, write the steps for your version out in your own document and re-read the documentation again to ensure you’ve captured all the steps.

My intent isn’t to cast aspersions on Sitecore’s upgrade documentation. Rather, my intent is to describe the level of difficulty an upgrade entails. If you’re a Jeep owner like me, you’ve probably done some modifications to it. Most of the 4WD specialty stores sell parts that are built specifically to bolt into specific makes, models and years of Jeeps. For example, a mirror mover kit can be purchased and installed to move the Jeep mirrors off the doors and onto the pillars supporting the front windscreen. This allows Jeep owners to remove their front doors and still be “street legal” with side mirrors. Each Jeep “mod” is stamped with a level of difficulty ranging from Easy to Difficult. The mirror mover kit was stamped “Easy”. My lift kit was stamped “Medium”. Changing out ring and pinion gears is stamped “Difficult” to “Advanced”. As an aside, pay someone else to do your gears unless you own a shop, have a lift and have done them before. Sitecore upgrades are stamped similarly achieving an “Advanced” rating.

The Upgrade Package

Sitecore upgrade packages consist of files and content items. These fall into the 3 CRUD categories (add, update, delete). When executed, they update the databases and the file system from the current version of Sitecore to the target version. In the “good ole days”, it wasn’t unusual to have to apply more than one package, especially when upgrading between versions that had more than one minor version in between.

Your Custom Code

Let’s not leave out your sizable investment in custom code. Renderings, custom pipeline processors, custom events and 3rd party integrations likely make up the majority of your custom code. In addition, there are likely a number of config files that patch in your pipeline processors and events. If you’ve followed some decent patterns you probably also have a number of config files that define the names and structures of indexes. Last but not least, the web.config needs to be updated. If you don’t make it a habit, please include your web.config in deployments. It’s an integral part of the solution. Assembly binding redirects, modules, handlers and app settings make up for the majority of the web.config that gets updated during an upgrade.

The Allure of “In Place Upgrade”

The documentation and update packages supplied by Sitecore invite licensees to perform an in place upgrade. As written, they almost compel one to attempt it. There is however, one caveat that isn’t spelled out clearly. An in place upgrade will generally only work for upgrading a vanilla Sitecore instance. If you’ve actually succeeded in performing an in place upgrade in the past, then you are a part of a small cadre of individuals who should be given a medal and a raise and bonus. Successful in place upgrades are about as rare Captain Ahab’s White Whale.

A Better Way

Whether you’re still on premise or you’ve made Azure part of your cloud adoption strategy, there is an alternative to in place upgrades that has an almost 100% success rate. I’ve historically referred to this as “Parallel Upgrade Strategy” and there may even be a blog from my past still floating around in the W3 ether that talks about it. I’ll try to do it justice here and apply some additional learnings.

Setting the Stage

Your timeline will vary compared to others based on a number of different factors but the steps will be the same. You will still want to thoroughly read through the documentation to determine all the steps necessary to perform the upgrade. You’ll most likely need to follow the flowchart and create your own document with the steps to upgrade your version to the target version. The steps you’ll follow are enumerated below and are based on upgrading from lowest environment up. Using “Fail Fast” strategy, you’ll want to upgrade locally first then engage DevOps to move into the upper environments.

1. Production Copy of Databases restored as new beta databases (call them Betabases if you want. I just made that up!).
2. Create a vanilla “beta” install of your current Sitecore version pointing to your “betabases”.
3. Alter the update packages — leave only the *Items folders, remove the *Files folders.
4. Create an upgrade branch in your source control repository.
5. Apply the steps extracted from the upgrade guide to your new vanilla install.
6. Upgrade your code
7. Deploy to the upgraded instance and target environment.
8. Test everything.
9. Repeat up to pre-production.
10. Freeze content for production upgrade
11. Repeat steps 1, 2, 5 and 7
12. Switch over DNS
13. Take a break.

While still fairly daunting, this approach creates a risk-free upgrade path that minimizes the impact to marketing and leaves the current site up and running. The content freeze for production upgrade can be really short-only the time it takes to stand up, deploy, backup, restore and upgrade the databases. In fact, you could cut a step out and have a new instance of Sitecore target version ready to go. The expectation is that you’ll most likely find some target environment changes at the 11th hour. This is usually within the configuration.

Code/Configuration Challenges

The biggest challenge with upgrading your custom code lies within the configuration files. If you’re moving from pre-9x to 9x or 10x, you’ve most likely embedded a number of configuration transformations in your configs. Moving to 9x and up, Sitecore has added role based configuration. This all but eliminates the need for configuration transforms.

The second challenge lies within moving from pre-8.2 up. Sitecore introduced dependency injection (finally!) in 8.2. This created a number of small but frustrating breaking changes. If you’ve used any of the guidance for multi-tenant Link Provider customizations, you’ll likely encounter a problem here. Link Providers have moved to DI so you’ll need to use Sitecore’s service locator and alter your code.

The third challenge I’ve hit lies [again] within patch files. For example, pipeline processes are usually patched in to get added before or after other pipeline processors. Major version upgrades may make older processors obsolete resulting in your patch file failing to correctly patch. The only way I’ve been successful in resolving these issues is by comparing the current version’s showconfig output to the target version to ensure that all my processors are present and in the right place.

The fourth challenge lies [again] within patch files. If you’re moving from configuration transforms to role based configuration, get really comfortable with ShowConfigLayers.aspx as of 9x. This replaces showconfig.aspx and allows a user to see what configuration will look like based on the roles defined on the target. You’re free to define as many role:requires as you want and configure for them. I’ve seen this go a little overboard on some engagements. Just be aware that you can alter the url to include all the other custom roles that have been defined to see what a target environment’s configuration is.

While the scope of this article lies outside upgrading and re-platforming to Azure, I’ll add here that the management of secrets and settings is super important. You may benefit from reading my other article on configuration management as it describes historical (and in some cases downright head scratching funny) and present day practices surrounding the management of secrets and settings. Suffice it to say that if you’re comfortable with the way you’re managing your connection strings and secret keys by all means leave it that way. If you’re not, I urge you to consider a hybrid approach if you’re remaining on premise and folding in Azure Key Vault and App Configuration. If you’re moving to Azure, you’ll need to add that step above as well.

Partnering With a Vendor

Of course, you can always partner with a vendor to help with your upgrade. Sitecore is a sizable investment as are your very valuable staff. An upgrade might be strategic but the actual work to do it is largely tactical. A very compelling reason to have a vendor perform your upgrade is to allow your staff to both learn from them and to learn how to leverage the features of the target version. With the advent of JavaScript Services (JSS), a much more mature Sitecore Experience Accelerator (SXA) and true Headless support, there’s a ton of new stuff to learn and master. Freeing up your staff to learn while the mundane work of upgrading is being performed by a vendor sets your organization up to maximize your Sitecore investment.