Upgrading from Umbraco 8 to Umbraco 9

• 06-01-2022

Recently, we have undertaken a number of customer projects to upgrade their existing Umbraco 8 websites to the latest version, Umbraco 9.

Here at Energise Technology, as a Umbraco Registered Partner, we have been eagerly awaiting the release of Umbraco 9.  From a technical perspective, it is a complete rewrite of the original product using Microsoft’s latest technology stack – meaning it will be actively developed, maintained, and supported for a number of years into the future.

There are a huge number of changes from Umbraco 8 to Umbraco 9.  Luckily from a user perspective, the user interface and ways of managing content are exactly the same, but “under the bonnet” there are some significant changes, bringing Umbraco right up to date with the latest development tools and techniques.

Firstly, Umbraco 9 has been redeveloped using Microsoft’s latest technology stack – a move from .NET Framework to .NET Core.  This will be Microsoft’s primary development language moving forward and will be the only one that is actively developed in the future.

This brings a number of benefits for Umbraco users and developers. 

More and more developers are moving to .NET Core just as Umbraco has, so we will have access to the latest development features as well as libraries and plugins.  Conversely, we may find that plugins and third-part libraries for Umbraco 8 don’t get updated as much in the future.  Microsoft has also committed to using .NET Core for the foreseeable future.

From a developer perspective, there is much to love about .NET Core as well, although there may be a small learning curve.  Generally, developers that have developed with .Net Framework have found it a very easy transition.

With Umbraco 8, we always started a website build with a blank Visual Studio project and then installed NuGet packages for the core Umbraco functionality. 

This has all changed with .Net Core.  To create a new project, you now need to install the templates on your development machine and then create a new project based on that template.  It’s very easy to do, just a bit different.

When migrating to Umbraco 9, our advice would be to start off with this blank project and then copy your files over bit by bit, fix any issues and then move onto the next section.  We started using the Models, then the services, and after that controllers and views.

… and one final point … don’t migrate against a live system.  Make a copy of the database and work against the copy as the database structure will be upgraded when it’s run and you’ve live system will grind to a halt.

Many users install packages and plugins which help them carry out tasks in the administration area.  Plugins we have used extensively in the past are SkyBrud for redirects, GodMode, and Usync for updating content.

While Umbraco has been redeveloped, before committing to migration, it’s worth checking that any plugins you rely on have also been updated to work with Umbraco 9.  It might be that you need to find an alternative way to achieve the same functionality or talk to the developer of the plugin to see what their plans for redevelopment are.

Even if there is a new version of the plugin available, it’s well worth checking that the plugins work correctly for your site – there may be bugs or issues which weren’t in the previous version.

One of the design goals of .NET core was that it should perform well and be highly scalable.

This means there are general speed improvements when moving from Umbraco 8 to 9, including quicker start-up times when the application is booted.

Performance improvements will depend on your specific application and how well the code is written, but you could see up to 20% speed improvement on page load speed.

While many of the changes you’ll need to make are quite straightforward (and repetitive), it is important to be aware of the scale of the changes you need to make when migrating.

The underlying libraries that Umbraco uses have changed and so as a minimum, the import statements will need to change to point to the new locations.

Also, there are different ways of accessing things like content and session information, now using dependency injection, so this will impact large parts of the code as well.

.NET Core also introduces some new concepts, such as ViewComponents, which will replace any ChildAction methods in your surface controllers.

A good time to make the most of new development features

With such wide-ranging changes, it’s a perfect opportunity to appraise the underlying codebase to see if code needs refactoring to make use of any new development features. 

Things like Dependency injection will simplify your code and make it much easier to test longer-term.  A review of things like error handling and logging can also help improve the code.

Something to bear in mind is that it’s very early days in the development of Umbraco 9.  This means we should expect there to be a few more issues and bugs that we had with the most stable version of Umbraco 8.

Unfortunately, the available information about Umbraco 9 is not as good as there currently is for Umbraco 8.  The documentation on the Umbraco website is very good and clear, but over time, there tends to be questions asked in forums or blog articles written that supplement the core vendors' documentation.  This obviously isn’t available in the same volume for Umbraco 9, so you might need to spend a bit more time investigating issues or functionality yourself.

We also found that some things just don’t work in the way they are documented.  One example for us was using the package to store media in Azure Blob storage.  No matter how we tried to use some options, they didn’t take effect, so ended up having to use it in a different way.  You may need to investigate workarounds around until issues are fixed or documentation improves.  Make notes of the workarounds you’ve used, so you can address them in the future.

One final gotcha for us was using examine searches.  The way one customer had implemented them in Umbraco 8 did not work when we migrated to Umbraco 9.  Again, there is limited documentation and examples, so we had to rewrite the search to fit with the new structure.

With such a structural change to the software, it’s important that testing becomes an essential part of the migration process.  All functionality should be tested well … every page, button, form posts, etc.  It is very easy to miss certain changes that may not show a warning or error in the development environment, and also compile and build but will fail when running.

There are test tools (particularly coverage testing) that will help identify any parts of the code that haven’t been run during the testing process.

If possible, it is worth creating a test environment that is very close to the production environment as well.  Because the underlying architecture is so different, it may interact with the webserver in a different way.  This is especially true with some plugins which would interact with underlying system files.