This is the second part of a devlog I started a week ago. Today, I am covering more documentation and highlighting some things that might interest you. Next, I get started with the upgrade and share some issues I encountered.
To give a bit more context, I am upgrading a Sitecore XP + SXA from version 9.0.2 to 10.1.0.
Reading the Installation Guide
Once the project started, I had another look at the Quick Installation Guide.
Because I installed Sitecore 10.0.0 once, I had everything I needed for the version 10.1.0.
If you are upgrading from an old version like 8.x or 9.x, here’s some of the requirements that might need your attention.
.NET Framework 4.8.0
As described in the link Sitecore compatibility table for Sitecore XP 9 and later, Sitecore 10.1.0 requires .NET Framework 4.8.0. This is the latest version of the .NET framework.
To check if you have it installed, in the .NET Framework installation folder - C:\Program Files (x86)\Reference Assemblies\Microsoft\Framework.NETFramework - have a look at which targeting packs are installed. For each pack there will be a folder with its version number.
.NET Core 2.1.18 Windows Hosting Module or later.
Some of the Sitecore components are built on .NET Core. e.g. Identity Server, xConnect, Publishing Services, and Horizon.
The version 2.1.18 is not the latest, though. Microsoft released recently .NET 5, which is basically .NET Core, but with a rebranded name.
You can check installed .NET versions on Windows, Linux, and macOS with the following command.
If you don’t have the .NET Core 2.x version, you can download the installer from .NET Core 2.1 (Linux, macOS, and Windows) (microsoft.com).
I recommend you installing the SDK.
MongoDB is no longer supported
In Sitecore 10.1.0, MongoDB is no longer supported as a database for session state and xDB Collection. You must use:
- Redis or SQL Server for the session state provider
- SQL Server for the XDB Collection databases
If you have analytics data on MongoDB, you need to migrate them with the Express Migration Tool.
Search indexing Solr / Azure search
Solr requires the version 8.4.0. This is the same version used in Sitecore 10.0.0.
Azure search is deprecated and will be removed in a future release.
Lucene has been removed long ago.
Highlights from the release notes
You should check the release notes from Sitecore 10.1.0, but I highlight some important changes below.
The upgrade process has been simplified. You can upgrade from Sitecore XP 8.1.0 or later directly to Sitecore XP 10.1.0 in one straightforward procedure. Basically, you don’t have a Sitecore Update Package anymore. Everything is carried out by SQL scripts and command-line tools.
Sitecore.UpdateApp 1.1.0 - This command line tool updates the Core, Master and Web databases. In Sitecore XP 10.1.0, the default items are moved into resource files. These items should be removed from your databases. The Sitecore.UpdateApp tool is designed to remove the unmodified Sitecore items from the Core, Master, and Web databases. The Sitecore items are not removed from a database if you have modified them.
The dedicated Reporting server role has been combined with the Content Management (CM) server role. This is to reduce hosting costs. You must apply any customization done in the Reporting role to the CM server role. Next, the Reporting Role should be removed from your architecture/hosting.
The new Data Purge CLI tool lets you remove unwanted contact data from the Experience Database.
You install it as a plugin to the Sitecore CLI.
PS C:\tmp\cli> sitecore plugin add -n Sitecore.DevEx.Client.Command.XConnect
Successfully installed version 1.0.0 of plugin Sitecore.DevEx.Client.Command.XConnect
PS C:\tmp\cli> sitecore plugin list
List of plugins: Sitecore.DevEx.Client.Command.XConnect v.1.0.0
The following commands are available.
PS C:\tmp\cli> sitecore xconnect -h
xconnect: Manage xconnect commands
Usage: sitecore.cli xconnect [options] [command]
-?, -h, --help Show help and usage information
registerDeleteContacts Registers the task to delete the contacts based on the provided conditions
cancelDeleteContacts Cancel the delete contacts processing task
getDeleteContactsProgress Gets the progress of delete contacts processing task
You register contacts for deletion.
PS C:\tmp\cli> xconnect registerDeleteContacts - 1 0.6 -4, 0.8 --b 1 -n tp
Registered task id: cd204140-68e6-4626-bfe7-5ddc3298af81. Please keep this task id to get the task status execution.
Next you can get a status of the deletion progress.
PS C:\tmp\cli> sitecore xconnect getDeleteContactsProgress t cd204140-68e6-4626-bfe7-5ddc3298af81 tp
ID : cd204140-68e6-4626-bfe7-5ddc3298af81
Created : 11/09/2020 09:29:38
Updated : 11/09/2020 09:29:56
Status : Completed Progress : 10
Total : 10
The Collection database now supports Scalable Reads.
Sitecore Fast Query has been deprecated. That means, you should migrate them as soon as possible.
Sitecore Fast Query is a feature designed for retrieving and filtering items from the Sitecore database. However, it has several issues and its usage has been discouraged long ago. To know more, I recommend reading this blog post from 2018: It's time to put fast:/ query to rest | Into The Cloud.
Here’s what using fast query will look in the code:
Sitecore.Data.Database database = Sitecore.Data.Database.GetDatabase("master");
Sitecore.Data.Items.Item items = database.SelectItems("fast:/sitecore/content/home/shapes/*");
Throughout the next sections and blog posts, I am covering what the Upgrade Guide determines. This doesn’t exclude you from reading it, though.
Before you start the upgrade, I recommend you checking the section 2.1.3 Important changes. This section outlines changes that occurred from version 9.0 up to 10.0.
Make a backup of your databases. This is recommended in case you want to rollback changes caused by the upgrade.
Download the upgrade files and tools available on the download page. You must download the package for the version of Sitecore XP that you are upgrading from.
Create a new branch so you don't mix the upgrade work with new releases in course.
Upgrade your solution
OK, so let's get our hands on the upgrade.
Update the target framework to version 4.8.
Depending on the amount of the projects you have in your solution - specially if you have a Helix solution, this might be a long and tedious task. You can use an open source Visual Studio extension called Target Framework Migrator. The source code is available at https://github.com/TargetFrameworkMigrator/TargetFrameworkMigrator.
This add-in will be available in the Tools menu.
In the Target Framework Migrator dialog, you select the projects and the target .NET Framework version.
One thing that this tool misses is to change the
targetFramework attribute in the packages.config (NuGet) files. This can easily be sorted with a Search and Replace All command.
Update Sitecore Nuget Package references to version 10.1
Next, we are going to upgrade the Sitecore NuGet packages.
This task is easily achieved by right-clicking the solution and clicking on Manage NuGet Packages for Solution...
During this upgrade, I found that some Sitecore references have been added directly into the project, but they were not referenced in the package.config file. These won’t show in the Manage Nuget Packages dialog. I advised you running a text search in the .csproj files looking for an older version text like 8.0.2.
Breaking changes when upgrading from version 9.0.2
Here, I list some breaking changes I encountered after upgrading the NuGet packages.
Sitecore.Abstractionsassembly has been removed. The code from this assembly was migrated to the
Sitecore.Abstractions.JobOptionsclass was refactored to
Sitecore.Abstractions.Jobclass was refactored to
Sitecore.XA.Foundation.VersionSpecific.Pipelines.PreAuthenticateRequest.SiteResolverwas moved from the
Sitecore.XA.Foundation.Multisitestarting from SXA 1.9.
Sitecore.ExperienceForms.Data.SqlServer.ISqlDataApiFactorywas removed: whatever SQL commands were being sent to Sitecore through the
SqlServerApiFactoryclass should be refactored. In my upgrade, I reimplemented it into the solution:
public interface ISqlDataApiFactory
public class SqlServerApiFactory : ISqlDataApiFactory
private readonly IConnectionSettings _connectionSettings;
public SqlServerApiFactory(IConnectionSettings connectionSettings)
this._connectionSettings = connectionSettings;
public SqlDataApi CreateApi()
return new SqlServerDataApi(this._connectionSettings.ConnectionString);
Sitecore.XA.Foundation.RenderingVariants.Pipelines.RenderVariantField.RenderResponsiveImage: The override method
CreateResponsiveImageshould now return
Sitecore.XA.Foundation.RenderingVariants.HtmlControls.CustomHtmlImage, Sitecore.XA.Foundation.RenderingVariants) instead of
Here, I list some warnings I encountered after upgrading the NuGet packages.
Sitecore.Resources.Media.MediaUrlOptions: use -
- In the custom views for Sitecore Forms, replace
Migrate local referenced Sitecore assemblies to Nuget Packages
If you have any Sitecore assemblies being referenced from a folder in your solution, you should migrate those to NuGet packages. This might occur, for example, when you have Sitecore Support patches installed.
Update Nuget Packages mismatches between the solution and Sitecore 10.1
Sitecore uses some specific Nuget packages and you should resolve any mismatches between the ones you use in your solution. This is either done by adding a binding redirect if you use a newer version or updating the version on your solution and recompiling it.
You can see the complete list in the link Assembly list located at the Release Information section in the download page https://dev.sitecore.net/Downloads/Sitecore_Experience_Platform/101/Sitecore_Experience_Platform_101.aspx.
This closes the second part.
We started with some documentation, then we jumped in into some prep work and closed with some tasks in the solution
Coming next, I'll be writing about the upgrade work on the databases and how I sorted some of the issues caused by the way the databases were exported.