In this tutorial, you will gain access to a solid plan and strategy on how you can tackle a Umbraco v7/v8 upgrade onto Umbraco v9 and above. If you are new to Umbraco, you should be aware that there was a significant change within v9. This change was the move from .NET Framework onto .NET Core.

I am not going to lie, moving from .NET Framework to Core is a big change. Some core Umbraco APIs have changed. A number of community plug-ins have dropped along the wayside. If that was not enough, there has also been a few architecture changes, like a completely new dependency injection container. In essence, the task of upgrading is probably going to be a large one. It took me just over a week to upgrade a fairly simple website.

Within this guide, you will get access to my experiences and thoughts on upgrading a Umbraco website. If you want to learn about one of the easier strategies for upgrading your website, this is the tutorial for you 🔥🔥🔥

Umbraco v9 Upgrade Website Steps

Throughout my career, I have performed well over 100 upgrades. These upgrade projects have ranged from different platforms, different programming languages, and different frameworks. From these experiences, I have created a pretty simple upgrade plan that works well. I have personally found that following this plan makes upgrading as painless as possible. Note, I said painless as possible and not pain-free 😕

There are a few different strategies for how you can upgrade a Umbraco website. The process that I recommend you avoid at all costs is the big bang approach. Trying to upgrade everything at once, and then being presented with thousands of errors can be a harrowing, daunting and frustrating experience. Any processes where you can move a little slower, one step at a time will make your life much easier, so how do you move slower? This plan defines my overall plan to upgrading within Umbraco v8 to v9:

  • Take a backup of your Umbraco database and web files
  • Create a blank database for your new Umbraco 9 website. Restore your v8 Umbraco database into this new database.
  • Go through a branch new Umbraco v9 installation so you have a vanilla Umbraco 9 build (steps here)
  • Open your Umbraco 9 project and open appsettings.json. Change the umbracoDbDSN connection string to target the new database you created above, e.g. umbracoDbDSN": "Server=.;Database=DocsSite;Integrated Security=true"
  • Re-run your website in a browser and you will now be presented with the Umbraco upgrade wizard progress. Follow the steps to upgrade the database.
  • After successfully upgrading try to log into the backend (/umbraco) with your admin account. If you encounter any issues see the troubleshooting section below. Sometimes the password might not upgrade correctly so fix that before moving on
  • After logging into the backend, regenerate Umbraco models builder and check the health status page. You will likely need to add some config with appsettgings.json to get this working (steps here)
  • Pick a simple page on your site and get it working. I do not recommend trying to get the homepage working first as the homepage tends to be pretty complex. I tend to pick something like a simple content page. To get the page to work copy the controller, view model and view from your existing project into the one solution. I recommend using a diff tool to do this copying as it will make your life easier!
  • Comment out any layout references within the page's view file. You want to focus on getting the page working on its own minus any site furniture like the header and footer. Trying to fix everything at once will take you longer and be more frustrating.
  • Compile the solution and fix bugs. This step will involve a lot of refactoring.
  • When the page is finally working, add the reference to the layout back within the view. Copy all the code related to generating the header, footer etc... from the old site to the new site.
  • Compile, test, refactor, and fix the issues
  • After the page and header and footer are working, repeat the process. Pick another page, rinse and repeat
  • After getting all the pages working, add any caching related code to the solution
  • Add deployment transforms, redirects, routing, etc...

By this stage, you should now have a fully working Umbraco 9 website . All your content created within Umbraco 8 project should now be working in .NET Core 😊

Obviously, this plan on paper looks easy enough to implement. In real life, sadly, it will not be this easy 😭

Expect to bump into lots of random code bugs. Things that once existed will be no more. With the introduction of things like view components and a change in DI containers, expect the possibility of completely refactoring and re-architecture how various bits of your codebase works.

There are tools like the Microsoft Upgrade Assistant which can help upgrade a project from standard to .Net 5, however, as a lot of the underlining Umbraco APIs have changed this tool will not be as useful as you might hope.

The Microsoft upgrade assistant will result in everything breaking at once, making it a complete ball ache to try and get everything back up and running.

I have attempted many upgrades and trying to fix everything in one big bang never works out well. I have managed to get the upgrade working every time, however, the process was a lot more frustrating and time-consuming than it needed to be. This is one of the reasons I recommend that you put all your custom code within separate class libraries rather than build everything within the website project. Being able to easily copy code between projects using a tool like Beyond Compare will allow you to more easily copy files and folders between two different projects.

Password Issues

If your site started life as a v7 website, you may encounter password issues after upgrading. If you cannot log into the CMS, you may need to reset the admin password.

This error can occur because there was a change to how passwords were salted between 7 and 8. If you can not log into Umbraco with your admin account you have two options.

You can add some SMTP details within appsettings.json and perform a forgotten password request. This can be done by adding this config with appsettings.json:

The alternative way (the one I prefer) is to use the Umbraco installer to reset the password. Following this appraoch, clean the database connection string within appsettings.json:

Re-run your site and the Umbraco installed will load. Add in your new admin username and password and then importantly click on Custom installation. Pick SQL Server as the database type and then add in your valid connections trying details within the database configuration screen. Run through the installation process and your admin password will now be reset 💥

Upgrading Considerations And Coding Issues

Depending which version of Umbraco you plan to upgrade from and to will depend on how much pain you will encounter. Within Umbraco v8 concepts like dependency injection, components and composers were introduced. A lot of the code syntax between v8 and v9 has changed, however, some of the fundamental ways of how you accomplish ting within Umbraco have stayed the same.

This is not the case if you are trying to go from v7 to v9. If you are on v7, you may want to consider a complete new build as the changes in architecture are substantial. For example, any code within your global.asax will have to be completely rewritten.

The recommendation is to go from v7 to v8 first, before attempting a v9 upgrade. Going this prolonged route is probably longer than a complete rebuild, so you may want to consider your options. Going new will likely be a less frustrating and quicker route.

When upgrading, a lot of your existing code will break. Expect issues everywhere, especially in:

  • Controllers (minimal)
  • Dependency injection re-configuration (minimal)
  • Composers and components (minimal)
  • Moving partial view references to view components (medium)
  • Caching (no output cache within .NET 5 out the box)
  • Config changes due to the move from web.config to appsettings.json
  • Syntax changes
  • Models builder modes have been renamed
  • Replacing deprecated Umbraco plug-ins and NuGet packages

As you can see this potential list of nastiness is pretty long. This list is also not an exhaustive list. My advice when upgrading is to go one step at a time. Do not try to fix everything all at once. Use reference material like my Umbraco 9 Youtube series to gain an understanding on how each component within the pipeline has changed and apply the correct fixes as you move along the journey.

Quick Coding Wins

The largest investment of time when upgrading will be the refactoring effort. Making .NET Framework code work in .NET Core is not a one-button click taks. Your refactoring challenges will range from small syntax updates to big architectural changes. As System.Web has gone, you will likely need to change a lot. For awareness, below highlights a high-level overview of areas you will need to refactor and a T-Shirt size of the effort you will need to invest in each area:

Umbraco Upgrade Effort

When it comes to tackling each area, expect to make smaller refactorings such as:

  • Changing all references in code toHttpContext.Current
  • Injecting new Umbraco services and APIs
  • Making small tweaks in order to successfully render properties from IPublishedContent like WriterName to WriterName(). The Umbraco Url property has also changed to a method called Url()
  • Within .NET Core, certain types are no more. Things like IHtmlString has gone. IHtmlString was used by a lot of the Umbraco properties like Markdown and RTE. This means that you need to make fixes within your view to make sure content renders as HTML. You will likely need to convert IHtmlString to something else. I opted to use Umbracos IHtmlEncodedString instead and then use Html.Raw() within my views as a halfway measure.

The code fixes and tweaks that you will need to make in order to successfully upgrade your website will be pretty substantial. The more complex the project, the longer it will take you.

In terms of upgrading being able to work on .NET 5 is nice, however, you will not notice any significant feature upgrades within the CMS within v9 compared to v8. After upgrading, your site will be much easier to upgrade to v10 and above which comes out in June 2022.

This invest of development time for little CMS gain is something every implementor will need to consider. Is the time and effort of upgrading going to provide enough value? For new builds use v9 onwards, for existing sites you definitely need to think about your project's lifespan. If your site is near the end of life anyway, maybe wait and do a completely new build with a new design later on instead.

Happy Coding 🤘