Treading the Bleeding Edge Path on a Big Umbraco Site

If you’ve been in any way involved in working with Umbraco in recent years you’ll have heard about the major overhaul to the back office that was coming in Umbraco 14, finally released at the very end of May. With a total rebuild from the ground up using all new web component technologies rather than AngularJS and spanning several years, it was inevitable the first release was going to have a lot more issues than we may have gotten used to with the by now battle-tested back office that had evolved over the past decade and still persisted up to Umbraco 13. Which is why they’ve been deliberate to label the Umbraco 14 release as a short term support release that you accept a little more work may be needed with it for now.

I wouldn’t normally jump on something which could almost be considered a bleeding edge release as I know I have quite a challenging site to start with. However for a change I was keen to see just how far I could get with the new release this early on. The TV Whirl site I far-too-regularly refer to on this blog is a personal site so I’m able to accept and work around more rough edges than you might be willing to hand to a typical client. But, somewhat unusually for personal sites, it’s also quite a large project, with over 60000 nodes between content and media and various custom hooks onto saving and publishing events, making for a very good base to test how things might go when you get into a more complex site rather than just throwing something simple at it. So the rest of this blog post serves as a little bit of a chart of the journey, in the hope it may help people work around a few teething issues, or decide where it might not work out for them at all.

As with any upgrade from an existing Umbraco version, the initial steps were the same – update the Umbraco package from Nuget and run the project. Initially for me this failed to run with a lot of complaints about missing libraries such as Smidge. Smidge used to be used for minifying and bundling assets like scripts and css together but was removed as part of a cleanup for Umbraco 14 due to no longer being necessary. Eventually it turned out this error actually came from the presence of Umbraco UI Builder which had been in use with the Umbraco 13 site. As of the time of writing this, the updated Umbraco 14 compatible version hasn’t yet been released, so for now it is simplest to remove it from the project as it comes with a lot of dependencies that are no longer present in 14. It’s also important when doing so though to make sure you do a ‘clean’ in Visual Studio to remove orphaned dlls from the bin folder, as a regular ‘rebuild’ isn’t enough to do this. Otherwise you may continue to get errors about dependencies like Smidge or Umbraco Licencing even though nothing appears listed in nuget.

With that taken out, I was able to get the solution to run, and attempted to follow through the normal upgrade process. But this is where I ran into my second early hiccup. Personally I have always used the manual or ‘attended’ upgrade process, requiring you to log in and agree to the upgrade. However on my solution, the login screen would get stuck in a loop. It would ask you to login to start the upgrade, but then immediately time out the session so be unable to continue. According to the logs on this, this seemed to stem from an error being hit when Umbraco checks for login tokens, specifically throwing an SQLiteException due to not being able to find database tables ‘umbracoUserGroup2Permission’ and ‘umbracoUserGroup2GranularPermission’ and a column ‘umbracoUser.key’. Despite my best efforts I’ve not been able to figure out exactly how to replicate this, as attempts to run an upgrade from both a fresh Umbraco 13.3.2 site and even right back to an Umbraco 13.0.0 site both went through fine, so it must be some specific combination or sequence of events on my solution which has led to this state. (Update 29/8/2024: Finally worked out how to reproduce this. The situation appears to arise if you had a site on v10 LTS originally, which was then upgraded to v13 LTS). However if you do run into this too (which is partly why I’ve included the table names in the blog post, for the benefit of anyone who may be Googling names), it can be worked around easily for now by switching on the unattended upgrade option in Umbraco instead (with thanks to Seb for the idea here). Even if only done temporarily, as unattended upgrades do not depend on being able to login first, it’ll let you complete the upgrade process. To enable unattended upgrades, ensure the following is present in appsettings.json:-

  "Umbraco": {
    "CMS": ...
      "Unattended": {
        "UpgradeUnattended": true
      }
    }
  }

With unattended upgrades turned on, the rest of the upgrade process went through smoothly, bringing me up a nicely running Umbraco 14 instance. For the most part, things on the front end of the site worked fine immediately, which makes sense as not a lot has changed with the front end rendering side of things. The only thing missing was that a lot of my images were not showing, so I dug into the back office to figure out what was going on here.

In my solution I use a lot of Media Pickers. I’d not realised it, but due to having a site which has been exported, reimported and upgraded many times over the years I was still using the legacy media picker, Umbraco.MediaPicker. Along with several other deprecated types, this is a type which has not been migrated to the new back office. After manually switching my document types to use the new media picker (aka Umbraco.MediaPicker3) fields instead, the existing picker data all showed up in the back office, and also restored all of the related data on the frontend of the site to full working order too.

So… did I move to Umbraco 14?

Alas, unfortunately at this point I did run into the few blockers which prevent me being able to use this properly at the moment. The biggest one is a current bug with the Umbraco Upload datatype, which my document types all rely heavily on. At present you can use these fields once when creating a new document, but once anything is in the field you are then unable to republish documents or delete anything from the field with back office returning a ‘Could not parse editor value to a FileUploadValue object’ error, rendering it impossible to subsequently edit anything further on my site. However having raised this on the issue tracker, it appears this is an issue which is already known about and set to be fixed in Umbraco 14.1.

The second issue I have presently is to do with the speed of big lists of child nodes. This one is partly a problem of my own making as I’ve long since been ignoring recommended advice. When you have a node with a large number of child nodes, it is recommended practice to use the list view setting on the parent node rather than having a large list appearing in the left hand content tree when you expand it. I’ve always found list view slower to browse through, what with having to traverse pages and such, so I’d stuck to just showing the list in the tree even for huge child lists of sometimes several hundred nodes. In Umbraco 14, this is simply not an option any longer. Only the first 50 items will be shown in the left tree, with ‘load more’ links needing to be clicked if you want to load in any more, though this rapidly seems to get slower so may not be recommended. I’ll keep an eye on this one, but I imagine this is a change I’ll have to make and at some point in the future I’ll just have to get used to using list view rather than tree view for this, but I’m kicking that can down the road for now.

So overall I’ve not been able to make the switch at this stage. However, to finish on a positive I don’t think it’s that far off. The biggest showstopper with upload fields is already in progress to be fixed with the first big rollout of fixes in a few weeks, and some of the other issues may just be workflow things I need to work on myself. But it’s worth highlighting here everything that did just work. My site frontend required absolutely no changes, once I’d corrected the back office use of the correct media pickers on the back office side. And from hooking on my VS debugger I can track that all of my more complicated hooks on both saving and publishing from the back office continued to work exactly as before, at least on the first publish anyway (subsequent publishes not testable due to the upload field type limitation mentioned above). I was expecting a lot more work would be needed on my site solution as part of such a big upgrade there, leaving me very pleasantly surprised. So I suspect by the time we get to about 14.2 and the new version of Umbraco UI Builder is out in the wild, I’ll be able to have another go at this and get all the way with it. And certainly I expect to be on the new back office well before v15!

It’s great to be able to be on the bleeding edge sometimes. But it looks like I’ll have to stay just that one step behind it for now!