Upgrade to Sitecore 9.3 – the easy way

Upgrade to Sitecore 9.3 – the easy way

Sitecore® Experience Platform™ 9.3 focuses on product updates and enhancements that increase usability and improve performance – all centered around making it easier and faster to build digital experiences so brands can accelerate their time to value. The new editing environment offers an intuitive interface with everything a user needs for easy navigation as well as real-time contextual insights as content is created and published, giving marketers the knowledge they need to drive improved conversions.

Other highlights can be reviewed on Sitecore site.

The decision to upgrade from your current to Sitecore XP 9.3 isn’t always the same.

Any upgrade to Sitecore XP 9.3 is more than a simple technical decision, however. An upgrade provides a great opportunity to revisit your content strategy and clean out the content in your WCM that is outdated or ineffective. It’s also the perfect time to re-evaluate your marketing strategy and develop new plans that enable the creation and delivery of unified, contextual customer experiences.

Another area that needs to take in consideration with the upgrade is Server Infrastructure.

Sitecore Cloud on Azure offers great efficiency in your ability to deploy and scale infrastructure on demand, while reducing on-premise costs. Using native Azure services and a pay-as-you-go usage-based model can simplify IT operations.

With Sitecore 9 you can still go with on-premise and IaaS models either in Azure or other data centers, but PaaS deployment may prove to be a game-changer for many organizations. This is a great juncture to re-evaluate your overall infrastructure and associated IT costs given the increased maturity of the Azure platform and available services.

2020 for me is the year of Sitecore upgrades so far. I was involved in 3 Sitecore upgrades, from different versions of Sitecore 8 to Sitecore 9.2 or Sitecore 9.3 with deployments both to PaaS and IaaS.

Before you start the upgrade, you need to asses the level of complexity the custom code has, because that will impact the upgrade time. Also take in consideration to use TDS or Unicorn to serialize Sitecore custom items to the file system and store them in source control.

Here are some integrations and features you need to take in consideration:

  • Dependency Injection – to avoid conflicts it must be changed if is not Microsoft DI used by Sitecore
  • Search, you should definitely consider using SOLR or Azure Search. Use Lucene only for a development or single server evaluation environment that runs Sitecore Experience Manager. You cannot use Lucene in a scaled environment. You can only use Lucene for content search. xConnect does not support Lucene. Sitecore does not recommend or support Lucene in a production environment.
  • ORM – may cause a lot of problems. In my experience Glass Mapper required a lot of re-work, Synthesis and Fortis, not so much
  • Custom Experience Editor buttons or menus – because need to be re-implemented in Speak
  • Sitecore modules that are no longer supported. The main one is Sitecore WFFM.
  • Custom Sitecore modules from Marketplace that need upgrade if you have the source code, or simply removed (PowerShell, 301 Redirects, Image Cropper – already part of Sitecore built in functionality…etc.)
  • Is Analytics enabled, if yes you need to take in consideration
  • Current infrastructure if it has anything specific

Now let’s start the upgrade. My solutions are built using Helix principles, more or less, and they use TDS to version control serialized custom Sitecore items.


  • Task1. Get database from Production.
  • Task2. Set up a new branch for Sitecore 8 and set up local solution to connect to Production database copies.
  • Task3. Sync TDS projects with Sitecore (that has production copy databases) to make sure that nothing was missed from TDS while developing features. Look carefully for core items.
  • Task4. Make sure you have an overview of all custom features implemented to all Sitecore Roles that exist on Production (ex. for Processing/Reporting) that may not be included in the VS solution.
  • Task5. Check what custom modules are installed/used and make sure you have a corresponded version for Sitecore 9 (ex. 301 redirects, PowerShell etc.) or look for alternatives (ex. WFFM -> Sitecore Forms)
  • Task6. Create a new feature branch where you will work on the upgrade.
  • Task7. Install Sitecore 9.3 on your local machine. Connect your TDS with the empty installation.
  • Task8. Create a copy of the empty website root to have it as a backup, to compare agains after you first compile the upgraded code.
  • Task9 – optional. Make sure you configure CI/CD for Test server. Release Pipeline should be connected to an empty installation of Sitecore 9 on Test server.

Execute Upgrade

Task1. Update Sitecore packages feed source in nuget config:

<clear />
<add key=”Nuget” value=”https://api.nuget.org/v3/index.json”/>
<add key=”Sitecore” value=”https://sitecore.myget.org/F/sc-packages/api/v3/index.json” />


Task2. Upgrade .NET Framework for all projects.

Task3. Upgrade Sitecore nuget packages to match Sitecore version you want to upgrade to.

Task4. Make sure 3rd party nugets are upgraded as well but make sure they match the version used by Sitecore => check Sitecore web config or directly the bin folder.

Task5. Consolidate nuget packages making sure same version is used on all projects that refer the package. You can also upgrade projects except TDS to use Package References instead of package.config.

On this step on some solutions I had lot of headaches because VS does not allow you to switch from package.config to package references because project type is not configured to allow it. A workaround for this is to edit the .csproj and remove temporary the ProjectTypeGuids line – this will transform your web application project into a class library project – and after you migrate to package references you can put the line back.


Task6. Compile the code. In this step you can decide to solve code conflicts and upgrade obsolete code.

Task7. Connect TDS with the empty installation of Sitecore 9 you want to upgrade too.

Task8. Deploy custom code on Sitecore 9.

Task9. Browse the site to make sure you do not have any incompatible assemblies.

Tip: You can compare bin files from website root back up (clean Sitecore Installation) with the bile files from website root containing custom code. Sitecore dlls should be the same (there can be some exceptions not referred in assemblies mapping)

Tip: You can edit nuget version from .csproj if you encounter problems upgrading packages using Package Manager.

Install Production Content

Task1. Install 3rd party Sitecore modules that are still relevant or have a compatible version with Sitecore 9

Task2. Take latest content from Production as normal Sitecore Packages: content, media, module items (ex. 301 redirect rules), users, roles

Task3. Make sure you comment out item events from config: \App_Config\Sitecore\Marketing.Operations.xMgmt\Sitecore.Marketing.config – it will throw errors when installing duplicate items (one client had  a lot of duplicate items)

Task4. Install Packages

Task5. Transfer user passwords. Use script: UpgradeScripts\TransferUserPasswords.aspx

Task6. Repair content.

Check for dynamic placeholder definition (supported by default in Sitecore 9 but with a different placeholder definition pattern). Use and change as needed the script: UpgradeScripts\FixDynamicPlaceholders.aspx

Check for Rendering parameters that have field names with spaces (will throw error for components used with personalization). Use script: UpgradeScripts\FixParametersFieldsWithSpaces.aspx.aspx

Compare master and web for unpublished content so editors can take care of it before Go Live. Use script: UpgradeScripts\CompareMasterWebContent.aspx        

Task7. Recreate forms using Sitecore Forms application if WFFM was used before.

Task8. Rebuild indexes and link database.

Task9. Use xDB Migration tool to migrate Analytics data.

You can download the mentioned scripts from GitHub

Code refactoring

Task1. Make sure you solve all warning and solve obsolete code.

Task2. Consolidate Dependency Injection to be same as what Sitecore uses. You can see the details of the dependency injection at this URL: http://[instance]/sitecore/admin/showservicesconfig.aspx.

Some objects like HttpContext is already injected.

Task3. Replace incompatible code.

Task4. Use config transform rules to overwrite Sitecore default setting to inject custom configurations specific to your custom functionalities.

Go Live Plan

Task1. Get artifacts from latest approved CI build.

Task2. Make sure you update configs for all Sitecore Roles (ex. Site Definition).

Task3. Install TDS update package.

Task4. Install custom code for each Sitecore Role if needed.

Task5. Install latest content from Production following Install Production Content Instructions.

Task6. If everything is OK update DNS.