Here at LEWIS, where I work, we have been watching, waiting and watching a bit more to decide when to start putting our clients on to Umbraco 8.
I've been using Umbraco 8 for a while on my own personal projects but they are small sites where if I run in to an issue it's not a massive problem. I just wait until the next release comes out and make do with what I have. From a clients point of view though this isn't ideal.
We had a team meeting a month or two ago and decided that once 8.1 was released, we would then start to put clients on to this version. We have an internal project which we use to kick start many of our projects. This was built in Umbraco v7 and over the past month I've have been migrating this over to Umbraco 8.1.
This article isn't a how-to guide or a tutorial on migrating from Umbraco 7 to Umbraco 8 but it may help those of you who are about to do something similar. It's a 'Look out for' sort of article. Things to keep in mind.
Before I go in to the things I've came across while migrating, I'd like to highlight a couple of things that made us decide to migrate once Umbraco 8.1 had been released.
- Version 8.0 had a couple of teething problems and things were still changing. 8.1 felt more stable and a good foundation to build from
- Umbraco Forms was now fully supported
- A number of third party packages had now been updated to work on version 8 which we use in our base build
- Umbraco Documentation was now coming online
- Umbraco HQ had issued instructions on how to migrate a site from version 7 to version 8
👍 It was time to take the jump.
As I mentioned, I was tasked with migrating our version 7 base line project to version 8.1
Over the past year, I've been doing a lot of upgrades for our clients. Some sites have been upgraded from 7.2 to 7.15 and I've got a system now in place which works for us here at LEWIS. Although our base project was on 7.14, I decided to upgrade our base to 7.15.1, this was the latest version at the time and it just felt right.
To do a site migration, the minimum version that the CMS needs to be on is 7.14.
⏰ You'll notice that I say site migration rather than site upgrade. There is no upgrade path from version 7 to version 8.
If there were any database changes within 7.15.1 then I'd wanted them to be there ready for the migration to v8. Maybe I was being a bit cautious but better to be safe than sorry.
Once the upgrade was completed, I followed the migration instructions from Umbraco HQ documentation
With the database now upgraded I thought I spin up the website locally to see what worked and what didn't. The simple answer was, nothing really worked from a frontend point of view. The backoffice was working and all my content was there, which was great. All I had to do now was make the required code changes to make the v8 site work.
Syntax changes
One of the first things you'll notice when you look at your code is a lot of error messages. Many of these are due to syntax changes within Umbraco's codebase. Things have changed, for the better might I add, but you won't be able to spin up your old Umbraco 7 site and expect it to work in Umbraco 8.
The dev team at Umbraco HQ have done an impressive job when creating v8 and they have cleaned out a lot of old code from the codebase. Code that was there from older version of Umbraco, code that was now redundant or obsolete. By doing this, they also refactored a lot of stuff and so this is why you will need to fix your own code and also why there is no upgrade path.
While fixing our baseline project I made notes and now I would like to share these notes with you. Some of this has been trial and error for me so if there are things that I have done which aren't best practice, please, let me know and I'll update my notes.
Things I found I needed to change or fix
Make sure your ASP.net framework is up to date!
If you have multiple projects within your solution, make sure they are all running the same version of ASP.net framework. Umbraco 8 runs on 7.4.2 and if you don't change both projects, you will run in to issues!
RJP.MultiUrlNodePicker is now in the Umbraco codebase
If you were using the package RJP.MultiUrlNodePicker in Umbraco 7, make sure you go in to the backoffice and reassign all your pickers to the new built in version.
Due to this change, my old code for picking out content from the MultiUrlNodePicker was now broken. e.g.
@if (siteSettings.SmallLogo3 != null && siteSettings.SmallLogo3Link != null)
{
<li>
<a href="@siteSettings.SmallLogo3Link.Url" target="@siteSettings.SmallLogo3Link.Target"><img src="@siteSettings.SmallLogo3.Url" /></a>
</li>
}
was now broken. To fix it I changed the above code to :
@if (siteSettings.SmallLogo3 != null && siteSettings.SmallLogo3Link != null)
{
foreach (var link in siteSettings.SmallLogo3Link)
{
<li>
<a href="@link.Url" target="@link.Target"><img src="@siteSettings.SmallLogo3.Url" /></a>
</li>
}
}
Nested Content
If you use Nested Content, I found I had to setup all my content options again. I also found that I needed to enable a new setting to make the Document Types accessible for use in Nested Content. You need toggle the 'Element' option on each Document Type from the Permission tab.
If you see this error cannot convert from 'Umbraco.Core.Models.PublishedContent.IPublishedElement' to 'Umbraco.Core.Models.PublishedContent.IPublishedContent' this is because you have a Document Type that you use within Nested Content that hasn't been set as an Element.
With some of the backoffice changes now made, it was time to tackle some of the code changes that I encountered.
Find and replace is your friend
Some of the changes in v8 can be fixed by using Find and Replace within Visual Studio.
- Search for x.DocumentTypeAlias replace with x.ContentType.Alias
- Search for RenderModel replace with ContentModel
- Search for x.GetPropertyValue() replace with x.Value()
- Search for Model.Site replace with Model.Root
Search and Indexing
This has completely changed and I'm still trying to get my head around it, however, there is good documentation on how to get started with the new way of searching within Umbraco on Our.
There is no doubt about it, if you use Examine in your v7 project, you will need to rewrite this in v8.
Are there other ways to migration from Umbraco 7 to Umbraco 8?
Yes! If for some reason you don't want to follow the Umbraco HQ way, you can check out Golden Gate, a package created by Callum Whyte.
Golden Gate by Callum Whyte
It's almost ready
With our base project now 90% migrated to Umbraco 8, all I have left to do is get search working and hopefully by the time you read this, I will have that completed. I've learnt loads and I'll be honest, we won't migrate all our clients on to Umbraco 8.
Why wouldn't you migrate a site?
We've decided we won't migrate sites that have a load of custom code within them. We have some pretty complicated websites, for example, mortgage calculators and multisite setups which we'll leave as is. If we had sites that were multilingual, I think we would take the time and effort to migrate a site though because v8 handles this so well.
We're not going to 'upgrade' sites from 7 to 8 when we do their monthly upgrade maintenance plan.
Should you migrate?
That is up to you but hopefully after reading this article you'll have an understanding of some of the things you need to keep in mind or watch out for. Each project is different and only you can really decide whether you want to or need to. Umbraco v8 is in a really good place now, the backoffice is a dream to work with and if you haven't tried it yet, I'd recommend downloading it and having a play.