Solution upgrade from Sitecore 9.01 to Sitecore 9.3

Recently I was involved in upgrading a Sitecore 9.01 solution to Sitecore 9.3. This was a Sitecore JSS based solution and it was quiet an interesting journey, so I decided to share with you some of the steps I needed to take to make this happen. Maybe you will run into the same thing.

Sitecore databases

For development environments in upgrade scenario's, my preference is always to start with a clean vanilla instance of the target Sitecore version. So I started by installing Sitecore 9.3. For an XP Single setup I could use the new Sitecore Installation Assistant with the graphical wizard to set it up. This went very smoothly after I made sure of the right prerequisites like SQL version etc.
I would then proceed in upgrading my solution, and deploy it to this instance and serialize the custom Sitecore items with Unicorn after the initial deployment.

Visual Studio project updates

One of the changes that took most of my time was switching from 'traditional' nuget package.config references to the new structure of Package References. The reason to switch to this is obvious as the benefits are quiet clear (as can also be read here), however to journey to get there with an existing solution based on packages.config was not so straightforward. Visual Studio 2019 doesn't seem to have great support for migrating to this new structure, at least not for the web project types that my solution had. I found a nice powershell script from Nick Wesselman here that helped a little in updating some of my projects (with a minor adjustment of updating to 9.3.0 as target version to use).
However, after running this script and opening Visual Studio, updating the nuget packages turned into some weird results. I don't know if it was due to how my solution was set up where maybe there were some weird dependencies between my projects, but the fact was that it resulted in a solution that did not compile due to resolving incorrect assembly versions. That looked something like this inside the VS project:

<PackageReference Include="Sitecore.Kernel" Version="[12.0.0]"> <Version>9.3.0</Version>

This became a cat and mouse game of updating project by project throughout my solution, but in the end I managed to get all references updated correctly. This wasn't difficult but a matter of perseverance.

While updating the references, it seemed like a good opportunity to also update all my other dependencies to the latest available versions on nuget, where possible. Consolidate all references etc.

Next to the package references change, I upgraded all my projects to .net Framework 4.7.2.

Compile it

Now that the right assemblies were referenced, I could focus on getting my solution to compile again.
There were a couple of changes in my code that had to be updated due to changes in Sitecore assemblies. One of them was in the upgrade to the latest JSS assemblies:

JSS Content resolvers
ContentsResolvers for JSS have a new rendering parameter to provide the context of the rendering to the resolver:

public class DescendantsRenderingContentsResolver : Sitecore.LayoutService.ItemRendering.ContentsResolvers.RenderingContentsResolver
{
        protected override JObject ProcessItem(Item item, Rendering rendering, IRenderingConfiguration renderingConfig)
{
            var jObject = base.ProcessItem(item, rendering, renderingConfig);

Deprecation
I identified some old unused classes that depended on Lucene. Now that Lucene is definately out of Sitecore 9.3, these were found easily and could be removed.

Deploy time issues

Once the solution started to compile, I could make a deployment to my new environment and check out whether it would start to work.

Identity
The implementation I was upgrading still depended on System.Identity implementation. After the first deployment this became apparant due to some nice initialization errors.
This dependency has been replaced a long time a go by Microsoft.Identity in the .NET Framework, however this only became apparant due to the dependency of Sitecore Identity on this newer version. For me this meant rewriting a few methods to use JwtSecurityToken instead of SecurityToken from the old namespace, and a different way to deal with validating tokens, instead of reading a certificate from the certificate store to validate, one now has to use only the public key to check the token validity.

Web.configNext it became apparent I needed to update quiet a few things still in the (web.)config.
With Sitecore 9.3 a new structure for connection strings was introduced.
I had to add config builders for connectionstrings due to new implementation for this in Sitecore:

<section name="configBuilders" requirepermission="false" restartonexternalchanges="false" type="System.Configuration.ConfigurationBuildersSection, System.Configuration, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b03f5f7f11d50a3a">
</section>
<configbuilders>
    <builders>
      <add mode="Strict" name="SitecoreAppSettingsBuilder" prefix="SITECORE_APPSETTINGS_" stripprefix="true" type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment, Version=1.0.0.0, Culture=neutral">
      <add mode="Strict" name="SitecoreConnectionStringsBuilder" prefix="SITECORE_CONNECTIONSTRINGS_" stripprefix="true" type="Microsoft.Configuration.ConfigurationBuilders.EnvironmentConfigBuilder, Microsoft.Configuration.ConfigurationBuilders.Environment, Version=1.0.0.0, Culture=neutral">
    </add></add></builders>
  </configbuilders>

I had to compare the vanilla 9.3 web.config with my own and needed to update the following:

• Quiet some assembly binding redirects needed to be updated to reflect the new package reference versions
• in System.webServer there are a bunch of new and updated modules and handlers
• New 'disabled' entries in membership and roleprovider sections
• In the compilation section I had to update the target framework version and assemblies, eg. the System.Web.Mvc version that is depended upon

For Unicorn to start working in 9.3, I had to enable the by default disabled file: Unicorn.UI.IdentityServer.config as described here.

Cache clear

The solution I was upgrading had an publish:end event configuration to do HTML Cache clearing for different site instances. In Sitecore 9.3 such behavior is default after a publish, and you have to actually disable HTML cache clearing explicitly for sites now, if you want to, so it actually works the other way around now. So for this I had to comment out/remove some config settings. Explanation can be found on SSE.

Test

Now I was able to deploy and do my initial Unicorn sync. After that load my application and it started to somehwat work! Yay!
Or wait, tiny detail: JSS SSR worked, but layout service calls failed. I forgot to move my api key from Core to Master database. Which is in master database in location '/sitecore/system/Settings/Services/API Keys'.

All in all, when I finally made my merge PR, the changes that were made were quiet clean and straightforward. To get there though, was quiet a journey which this time wasn't made very easy by the tooling (VS2019). But in the end I got there.

These were my lessons learned. Hope they are helpful to you. If you have any question on details of this journey, please reach out to me on Sitecore slack (@joost) or on Twitter (@djewst).