25 Feb 2021 - Rohan Pandit

Learnings from a Sitecore Upgrade and Azure PaaS Migration

Screen Shot 2021-02-24 at 3.09.58 PMUnfortunately, right now there is no simple way to upgrade Sitecore versions with a click of a button. There are many steps involved that all work in tandem in order to successfully deploy the upgraded version of your Sitecore environment. Migrating to Azure PaaS is also an extra step which added to the overall complexity of our process. This article outlines some of the challenges encountered and the subsequent learnings.

In our particular case, we were upgrading a Sitecore XP 8.1 instance to Sitecore XP 9.3. The key differences between Sitecore 8.1 and 9.3 include the creation of Sitecore Cortex, the machine learning and artificial intelligence feature, Sitecore xConnect which decouples the data storage in Sitecore CMS and allows for easier and better integration to that data from within the application, a new Marketing Automation feature, enhancements to Sitecore xDB by changing the way the data is stored, and making the whole Sitecore platform smaller and lighter in order to more efficiently hosted on the Azure PaaS infrastructure.

The method we employed in order to successful upgrade our Sitecore 8 version to Sitecore 9.3 was the “Life and Shift” method, which involved the following:

  • Downloading and installing a brand new fresh Sitecore 9.3 environment into Azure PaaS
    • Steps for this are well documented in other online articles, so this process is not addressed here
  • Massaging Sitecore 8.1 databases into the Sitecore 9.3 databases
  • Updating configuration in Sitecore 9.3 to match the configuration in the Sitecore 8.1 instance
  • Updating deprecated core code as well as additional libraries like Glass

Once we successfully deployed a brand new Sitecore 9.3 version in Azure, it was time to get to work and take care of the following items in order to launch our fully functioning and migrated Sitecore 9.3 site:

  1. Database
  2. Configuration
  3. Code
  4. Azure Configuration


For better or for worse, data migration during the upgrade process is not as simple as taking a database dump of core, master, web, and analytics/reporting and then importing into the fresh Sitecore 9.3 instance. The change in architecture of the databases in Sitecore 9.3 due to the changes in xDB and the introduction of xConnect, can cause many issues. Thankfully, there is a very handy tool called Razl which is part of the Sitecore Developer Collection tools.

Razl was a saving grace in our efforts to seamlessly migrate data over to the upgraded Sitecore 9.3 environment.

Database image

The tool connects two instances of Sitecore and does a full database compare of the selected database. After the comparison, you can migrate the data you need easily. The reason why this tool is effective in the data migration is that the functionality is built on top of the same API that is used within the CMS to create and install packages for deployment, and it can properly massage the data from Sitecore 8.1 to Sitecore 9.3 database schemas.



One of the most difficult parts of the upgrade includes figuring out what configuration needs to be moved from Sitecore 8.1 to Sitecore 9.3, and where it should be placed. If you made the mistake of not properly applying patch files to custom configuration, this may be a bit of a difficult task, but it is doable.

After identifying all the custom configuration on our Sitecore 8.1 instance, we needed to figure out how the new configuration was setup within Sitecore 9.3. One of the biggest changes to the configuration setup was moving many entries that are in web.config at the root level of the 8.1 instance out to a new Sitecore.config file within the App_Config folder.


Another configuration change that needs to occur is the switch from Lucene to Solr for indexing if you are using Lucene on your current setup (which we were). In order to make this transition, you have to disable Lucene configuration and enable Solr by adding the configuration. Additionally, you’ll need a specific Solr service and the Sitecore data must then be reindexed through the CMS into the Solr indices. You can opt to use Azure Search as well, but for our upgrade we used Solr. Patience is key in identifying and porting over custom configuration, and in our experience, expect a lot of time to be spent in this step.



Depending on the complexity of your Sitecore environment and site, there may be a lot of code changes involved. The main reason for this is deprecated core code when upgrading your Sitecore version. Additionally, if you have used the wonderful Glass library to easily work with Sitecore items within the code, there are a lot of changes required there as well.


Sitecore 8.1 was only compatible with Glass through version 3, Sitecore 9.3 requiring Glass version 5. This caused many issues during the code updates. Similar to the configuration updates required, this step requires a lot of patience to make sure you update all deprecated code, whether it is core code you are using within your instance, or any additional libraries you are utilizing.


Azure PaaS Configuration

The original setup for our Sitecore 8.1 instance was the cloud IaaS deployment model, namely virtualized servers, that did not provide the necessary flexibility and scalability that Azure PaaS delivers.

The initial steps involved in the migration to Azure PaaS were the provisioning and configuring of multiple App Services that acted as the Content Management and Content Delivery services. With a solid PaaS infrastructure configured to support our initial fresh Sitecore 9.3 it was time to utilize a similar “Life and Shift” method to move the necessary code, data (using Razl again) and configuration to the PaaS environment in Azure.


Consult with a Marketing Tech Expert