Tips when upgrading Umbraco from 10 to 13

I recently upgraded a website from Umbraco 10 to 13. In this post I present a list of things that you may want to look out for when doing this yourself.

Practice your upgrade

Despite being one of the easiest upgrades ever, I still recommend practicing your upgrade. Take a copy of your production database, place it locally and see what happens when you upgrade. The upgrade didn't quite work for me on the first try, especially upgrading 3rd party plugins can pose some additional challenges.

I also noticed that on my local setup, not all migrations were run at once. Even though the upgrade was completed according to the logs, after a reboot, the application was still running additional package migrations from Umbraco Forms, among other things. Thanks to my upgrade practice, I knew to expect this.

Use unattended upgrades

I think the unattended upgrade is the best setting for doing upgrades. So long as the upgrade hasn't finished, your site won't load. In my experience, this makes the upgrade more reliable (potentially subjective). I've personally seen less errors in my logs. Also the UI gives an error if the upgrade doesn't finish before the request times out and I find that confusing and unsettling.

Configure logging

One other thing I noticed during practice, was that without information level logs, I couldn't see how far the upgrade was and what was happening and if the upgrade was done or not. Now on a production environment it's not recommended to log information level logs, so I recommend setting your log settings to something similar to this:

{
    "Serilog": {
        "MinimumLevel": {
            "Default": "Error",
            "Override": {
                "Microsoft.Hosting.Lifetime": "Information",
                "Umbraco.Cms.Infrastructure.Migrations": "Information"
            }
        }
    }
}

By overriding the logs in these namespaces to Information, you can see which migrations Umbraco is running by monitoring the log files and if you run unattended upgrades, the hosting lifetime logs show you when the application has started, which is a nice indicator that the upgrade has finished.

Give it time

The database upgrade took about 20 minutes for me to finish. Especially updating the property data table took quite long and sometimes I was tempted to give the website a kick. Don't do that, just be patient and wait until the application boots or does something.

Check your xPath queries

In my U10 site, I used a lot of xPath queries that looked like this: //myDocTypeAlias. These xPath queries don't work anymore in Umbraco 13. I recommend checking all your xPath queries and either replace them with something else or check if they still work. These are some places where you may want to take an extra look:

• appsettings.json (think configured error pages and similar)
• multinode treepicker datatypes
• Calls to methods like .GetSingleByXPath() or similar

Check your richtext editors

It turns out that the config of the richtext editor has slightly changed. I don't know for sure if the config is automatically upgraded, but I noticed that the style dropdown had disappeared on all my richtext editors, so that is something to keep an eye on.

Use uSync

You will find that after the upgrade, you need to fix some of your datatypes by hand. What you should do, is run the upgrade locally on a copy of your production environment, do all your manual changes and then do a uSync export on your settings. You'll be very grateful for it. On your next try, you can let uSync do all the manual corrections for you after the site has upgraded! It's a big timesaver!

Check your usage of Link objects

We used to serialize Link objects to json in api endpoints among other things. After the upgrade, we found out that now the Link object contains a reference to IPublishedContent. This object is not serializable, so you should replace it with something else if you return it in an api endpoint. Should you find yourself short on time and unable to replace the model, you could take this extension method as a shortcut (credits to my coworker for this snippet of code):

public static class LinkExtensions
{
    [return: NotNullIfNotNull(nameof(link))]
    public static Link? WithoutContent(this Link? link)
    {
        if (link is null) return null;

        return new Link
        {
            Name = link.Name,
            Target = link.Target,
            Type = link.Type,
            Udi = link.Udi,
            Url = link.Url,
        };
    }
}

This code excludes the IPublishedContent from the model, so then it is serializable. This is obviously not pretty, so prefer to get rid of this later.

Check your indexes

If you have custom indexing logic, have another look at it and see if it still works after the upgrade. I got an error in the index because I used some exotic features with content variations and it turns out that the index in Umbraco 13 had some problems dealing with it. In particular, I had to explicitly assign an empty VariationContext to the VariationContextAccessor before extending the index to prevent null-ref exceptions.

Additionally, Jason on Discord pointed out the following:

This is kind of a known issue, but it doesn't seem to affect everyone and I don't think anyone really knows why.
Firstly, be sure to use the settings here: https://docs.umbraco.com/umbraco-cms/fundamentals/setup/server-setup/azure-web-apps
Secondly, if you're running v13.2+ try setting the "SiteName" in appsettings to a different value for each slot.

  "Umbraco": {
    "CMS": {
      "Hosting": {
        "SiteName": "SomethingUniqePerSLot"

This will force indexes to be stored in different locations. Without it the indexes can get locked because of how Azure warms up slots for swapping. You can see the full details in the PR here.
https://github.com/umbraco/Umbraco-CMS/pull/15571

I configured this option and haven't seen any negative side effects to it. I don't know how bad this problem is, but I think it's good to configure this regardless, just in case.

Crawl your upgraded site

If you have the opportunity, I recommend using a web crawler like Screaming Frog's SEO Spider. It's an easy way to call every page on your website and it increases your chances to spot any breaking changes.

Conclusion

The upgrade was incredibly smooth in my opinion. Umbraco has done a great job at managing the breaking changes and simply following the instructions was pretty much enough to make the step from 10 to 13. The biggest challenge was upgrading packages, but even that wasn't thát difficult. I'm very happy with the result.

That's all I wanted to share. I hope it's useful for some of you. Thank you for reading and I'll see you in my next blog! 😊