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.

dotnet --list-runtimes

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.

Sitecore.UpdateApp.exe clean

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] 

Options: 
-?, -h, --help Show help and usage information 

Commands: 
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. 
PS C:\tmp\cli>

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 
PS C:\tmp\cli>

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/*");

Upgrade Guide

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.

Before upgrading

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.Abstractions assembly has been removed. The code from this assembly was migrated to the Sitecore.Kernel.
• Sitecore.Abstractions.JobOptions class was refactored to Sitecore.Jobs.DefaultJobOptions.
• Sitecore.Abstractions.Job class was refactored to Sitecore.Jobs.DefaultJob.
• Sitecore.XA.Foundation.VersionSpecific.Pipelines.PreAuthenticateRequest.SiteResolver was moved from the Sitecore.XA.Foundation.VersionSpecific to Sitecore.XA.Foundation.Multisite starting from SXA 1.9.
• Sitecore.ExperienceForms.Data.SqlServer.ISqlDataApiFactory was removed: whatever SQL commands were being sent to Sitecore through the SqlServerApiFactory class should be refactored. In my upgrade, I reimplemented it into the solution:

using Sitecore.Data.DataProviders.Sql;
using Sitecore.Data.SqlServer;
using Sitecore.Diagnostics;
using Sitecore.ExperienceForms.Data.SqlServer;

public interface ISqlDataApiFactory
{
    SqlDataApi CreateApi();
}

public class SqlServerApiFactory : ISqlDataApiFactory
{
    private readonly IConnectionSettings _connectionSettings;

    public SqlServerApiFactory(IConnectionSettings connectionSettings)
    {
        Assert.ArgumentNotNull(connectionSettings, "connectionSettings");
        this._connectionSettings = connectionSettings;
    }

    public SqlDataApi CreateApi()
    {
        return new SqlServerDataApi(this._connectionSettings.ConnectionString);
    }
}

• Sitecore.XA.Foundation.RenderingVariants.Pipelines.RenderVariantField.RenderResponsiveImage: The override method CreateResponsiveImage should now return CustomHtmlImage (Sitecore.XA.Foundation.RenderingVariants.HtmlControls.CustomHtmlImage, Sitecore.XA.Foundation.RenderingVariants) instead of HtmlGenericControl (System.Web.UI.HtmlControls.HtmlGenericControl, System.Web).

Deprecated

Here, I list some warnings I encountered after upgrading the NuGet packages.

• Sitecore.Resources.Media.MediaUrlOptions: use - Sitecore.Links.UrlBuilders.MediaUrlBuilderOptions instead.
• Sitecore.Links.UrlOptions: use Sitecore.Links.UrlBuilders.ItemUrlBuilderOptions.
• UrlOptions.DefaultOptions: use new DefaultItemUrlBuilderOptions().
• In the custom views for Sitecore Forms, replace Model.CssClass with Model.CssClassSettings.ManualCssClasses;

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.

Conclusion

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.

Credits

Photo by Markus Winkler from Pexels.