Is It Time for Upgrades?
With the Umbraco v7 fast approaching its End Of Life on September 2023 and v8 entering its security-only phase on February 2024, it is time to upgrade Umbraco v7 and v8 projects to the latest version of Umbraco.
By moving your projects to the latest version of Umbraco, you will directly benefit from the latest performance and security improvements of Umbraco CMS and .NET 7 as well as many new features of them, including a lot of fantastic Umbraco packages.
But considering there is no direct upgrade path from Umbraco v7 to Umbraco v8, then how can you do your Umbraco upgrades?
This is a question that I asked myself many times.
My first Umbraco v7 upgrade to v8 was in 2020. At the time, there were a lot of unknowns and I wanted to create some know-how for my company and the Umbraco community. After a lot of suffering, I concluded that it was very complex to upgrade a v7 project to v8. This, of course, didn't change the fact that I needed to upgrade v7 projects to the later versions of Umbraco, so I kept on digging.
I read the constantly evolving official Umbraco documentation many times, attended meetups and conferences, watched a lot of YouTube videos, and asked many questions to Umbraco HQ & Umbraco Community.
In the end, I have come up with 12 steps to do the v7 upgrades.
What Upgrade Options Are There?
There is no direct upgrade path from Umbraco v7 to v8 due to the code base being very different, but content migration is possible.
There are multiple approaches for upgrading your projects.
If you have a lot of custom code, a better option could be to spin a new Umbraco v11 website, create all your Umbraco objects and then write some scripts to do your content migration.
Another option could be using some 3rd party software, so that you could push all your content changes into this software and then get your content directly from there for your v11 website (after doing some data transformations).
In this post, I followed a different approach that worked for me. This is an approach that is worth trying and recommended by a lot of people within the Umbraco community.
Upgrade Steps
Step 1 - Create back-ups!
It is always a good habit to create backups for your source code and database before and after each step.
Step 2 - Make sure your v7 version is min 7.14.0
If not, then upgrade your v7 project to min 7.14.0, ideally to the latest version of v7.
Step 3 - Clean up all the things that you won't need
If you don't need some of your data, then delete it. Also, empty your Umbraco project's recycle bin and clean up your database version history - you can use the UnVersion package or run your own SQL script to clean up your database version history.
Step 4 - Run pre-migration health checks
Use the "Pre-migration health checks" package for this.
This package will help you identify some problems which may prevent the database from being migrated to v8, so it is important. If there are any problems, fix them before jumping to the next step. At this point, I’d also recommend you to read this great blogpost by ProWorks so that you won’t miss the important details about Umbraco version “thresholds”. Also, take a look at the new uSync Migrations tool as well as some other approaches, like Moriyama’s approach or Enterspeed’s integration apps.
I used the Packages section in Umbraco backoffice to manually install this package using its zip file.
Step 5 - Spin up a new v8.5.5 website
It is important to spin up a new v8.5.5 website as v8.6 has some migration changes that break the v7 to v8 migration.
Alternatively, you can try to go to a higher version of v8 using ProWorks.Umbraco8.Migrations package.
In any case, make sure that you can log in to Umbraco back office and do not create any Umbraco objects, yet.
Step 6 - Update the v8 web.config file for the connection string and Umbraco version number
Replace your v8 website's connection string with the v7 connection string. Also, update the Umbraco version from 8.5.5 to your v7 website's version number. "Umbraco.Core.ConfigurationStatus" is where you'll find your Umbraco version number.
These changes will trigger the content migration when you run your v8 project.
Step 7 - Build and run the v8 project and complete the database upgrade as well as the content migration
It is time to build and run your project now. I recommend running your project without debugging.
After running your project, you should see the Umbraco installer screen which should upgrade your database and files. This should also do the content migration.
Depending on the complexity of your project, you might see some problems. There are quite a few answers on Umbraco Forum and StackOverflow, hopefully, some answers would help you.
If all has been good, then you should be able to log in to your new v8 website's Umbraco backoffice and see your content.
If you end up seeing more and more problems, you might want to consider a different approach for your upgrade.
Step 8 - Upgrade your v8.5.5 project to the latest version of v8.
If you have reached this point, then you should make yourself a nice cup of coffee (or something stronger) and enjoy it because you have just completed the trickiest bit of your upgrade. 👏👏👏
Upgrade your v8 project to the latest version of v8 and get ready to move your project to .NET 6 and v10!
Step 9 - Spin up a new .NET 6 v10.0.1 website
Spin up a new v10.0.1 website and complete your database installation without creating any Umbraco objects.
Make sure you can log in to the Umbraco backoffice and things are good. You can potentially try using the latest version of v10, but I wanted to be as close as possible to v9, hence chose this version.
Step 10 - Update your appsettings.json file and start using the v8 connection string for your v10 project
There is no way to directly upgrade your v8 website to v10. This is due to v8 running on .NET Framework and v10 running on .NET 6, but you can once more migrate your content.
After updating the v10 project's connection string to use the v8 project's connection string, run your v10 project - this will once more trigger the database upgrade and the content migration.
As the v8 database schema is very similar to the v10 database schema, things should easily be upgraded and migrated at this point.
Once all is done, log in to your v10 website's Umbraco backoffice and check your content.
Step 11 - Upgrade your v10.0.1 project to the latest version of v10 and then v11.
It is time to upgrade your v10 project to the latest version of v10 using the Package Manager Console. Once the v10 upgrade is complete, then upgrade your project to .NET 7 and the latest version of v11. Make sure all is still good after your latest upgrade.
Step 12 - Create your custom code
This is the final step of your upgrade. You can now create your custom changes for your brand-new v11 website and create new Umbraco objects or update them or do other things that you need to do like creating templates etc.
Final Note
In this post, I've created 12 steps that should hopefully help you with your Umbraco v7 upgrades to the latest version of Umbraco.
Depending on the complexity of your projects, you might have some additional steps, and if you do, please remember to share your knowledge with the rest of the Umbraco community.
And finally, big thanks to Umbraco and Umbraco community to help me create this post. #h5yr