In this article, I will share my honest experience of upgrading this website from Umbraco 7 to Umbraco 8. If you are not aware, V8 is a big step away from V7. Depending on the complexity of your site the upgrade path might not be straightforward. My site relied heavily on some community packages that were deprecated in V7. Due to this, I resisted upgrading for a long time as I knew it was going to be painful. In the end, it took me 10 solid days to upgrade my site which for a simple site is quite a long time!
Historically, some of the Umbraco upgrade paths like V6 to V7 were pretty straightforward. In V8 the Umbraco architecture changed a lot. Fundamentally API changes have been introduced. Umbraco has moved towards a more decoupled architecture, supporting dependency injection out of the box, which is great. This means the jump from V7 to V8 is not straightforward. If you need to upgrade your website, and you want to ease the pain of upgrading, then read on!
❗ Prerequisites Are Important ❗
When you decide to upgrade your site, you might be tempted to skip reading the V8 pre-requisites that are listed on the Umbraco site, but, DON'T. As someone who has never read a single instruction manual for pretty much any gadget that I have ever brought, I also skipped reading the V8 upgrade instructions. The result from this decision was me wasting about a day of my life messing around and fixing things that would have worked if I had just RTFM. To re-cap before, you need to:
Ensure you have at least Visual Studio 2017, upgraded to V15.9.6. The installer will not work below this. Not upgrading my VS before upgrading wasted a lot of time 😢
Ensure .NET 4.7.2 is installed
Upgrade your site to the latest version of Umbraco 7.15 first, before you attempt to jump to V8
The Upgrade Process From Umbraco 7 To 8
The upgrade process can be boiled down into these steps:
Upgrade the Umbraco NuGet packages
Run the Umbraco installation wizard to upgrade the database
Fix your code
Upgrade The NuGet Packages
I thought that upgrading the Nuget packages would be easy, however, it took me over half a day. My main tip to make this step as easy as possible is to follow the advice in the prerequisites. If you do not have the correct version of Visual Studio, the correct version of .NET installed and also each project in your solution set to use 4.7.2 the Nuget packages will fail to install. When I tried to upgrade the Umbraco Nuget package, I got this error:
If you encounter this issue, re-check that all class libraries and projects in your solution are set to use .NET 4.7.2. In Solution Explorer, open the right-click menu for the project that you want to change, and then choose Properties. Choose the Application tab. In the Target Framework, choose the version that you want.
After doing that, go into Nuget solution explorer and make sure you update these packages UmbracoCMS, UmbracoCore and Umbraco.ModelsBuilder. You need to make sure that each package you upgrade is applied on a solution level. If you have references to different versions of the same assembly within your solution then the upgrade will not work.
TIP When upgrading Nuget I encountered a strange caching issue that made it look like my packages had been updated when they hadn't. I recommend that after you upgrade the core Umbraco packages you clear the NuGet cache. You can do this using this command:
After upgrading the Nuget packages to the V8 versions all hell broke loose in my solution! At this stage in the upgrade process, all you really want to do is run the installation wizard to upgrade your website to v8. To do this, you need the website to compile. When I tried to compile the site after upgrading the site, I had over 6000 errors :(
The best way to get the Umbraco installer to run in this situation was to comment out every single line of custom code in my project. This step took me about a day, however, I eventually got the site to compile! After getting the upgrade wizard to launch, unfortunately, the installer failed midway! As mentioned above I did not read any prereqs so I tried to upgrade my site, from 7.4 to 8.1 directly. This is not a viable upgrade path. You need to upgrade the site to 7.15 first. Do not forget to do this!
WARNING You also need to make sure the V7.15 site is working. Do not simply upgrade the Nuget packages without checking anything 🤪. As part of the upgrade to 7.15, some of the core data types changed and others had become obsolete. Having these obsolete data-types referenced by my document types made the V8 installer to crash. I needed to fix them before I could carry on. To fix a data-type, log into the editor and click through all the document-types and data-types (in the settings section). If you see anything with (obsolete) within the name, you will need to update and fix these otherwise the v8 upgrade wizard will fail.
This step was really frustrating, as it caught me out a few times. Each time the upgrade wizard failed due to obsolete properties, I had to revert all my packages to 7.15, open Umbraco, check the types to find the ones that I had missed and fix them. After this, I had to go through the process again, re-upgrade the Nuget packages and try running the installation wizard again. It would have been simpler if Umbraco could have generated a report that details all the problem properties within the website, rather than me manually needing to hunt for them. This to'ing and fro'ing wasted several hours, so my advice is to triple check when you do this.
Another issue that happened because I was constantly upgrading and degrading packages. Some values in my web.config got overridden with blank values which broke even more things. When upgrading I suddenly encountered this error:
Somehow when the UmbracoCMS Nuget pack ran, the Umbraco.Core.ConfigurationStatus setting within the web.config was overridden with a blank value. This meant the CMS failed to load. To fix the error within the web.config I had to update this value:
Eventually, the upgrade wizard ran and finished without throwing an error! However, there was still a final hurdle. I could no longer log into the CMS. In V8 the way passwords are encrypted has changed. If you try to log in and Umbraco tries to decrypt the passwords using the new method it will fail. If you can not log into Umbraco after upgrading, check that the uselegacy property on the membership provider has not changed!
After the database upgraded successfully, you now need to uncomment all your custom code and fix it. This took me several weeks. I will cover some of the main refactorings I had to make in the next tutorial here. For now, just be happy you have upgraded the Nuget packages and database! Happy coding!
