Blog: How thinking in smaller steps can help bridge the Umbraco 8 migration gap

Now Umbraco 8.1 has been released along with a handy Content Migration Tool to help you to migrate content from an existing Umbraco 7.14 database, we’ve been asked lots of questions from our clients regarding the migration. What’s involved, is it automatic… and is our site ready to move to V8? And in some circumstances is V8 really ready for our site yet!

We’ve been working with some of these sites for 5+ years, migrating through from Umbraco v4 to v6 and onto V7, they are like old friends! And old friends, when they come to stay, often come with baggage... 

Here at Moriyama, we follow a philosophy of improvement (where possible) through iterative and incremental changes - no changes just for change's sake! We aim to proceed mindfully and step by step, delivering improvements quickly and above all regularly.

But this leaves us with a bit of a dichotomy with v8 migrations. How can we take smaller steps in an upgrade/migration that demands a rewrite of your template syntax?

Umbraco 8 vs legacy code

(from The steps to migrate content from V7.14 to V8.1)

Umbraco V8 is a bit of a reset! - in order to achieve a platform that will be easily maintainable over the next few years, as it moves to .net Core etc - large amounts of backwards compatibility for techniques stretching back as far as Umbraco v4, have been dropped - for example, there is no support for WebForms, Dynamic Razor - and many helpers, methods and classes have been ‘renamed’ with common sense in mind, this is a very good thing! - especially for new people adopting Umbraco…  but...the one casualty is the migration of existing template syntax and custom code into the new V8 approach - and the suggestion is to recreate all templates and custom implementation from scratch to allow your migrated Umbraco site to work again in V8.

For example: with an older Umbraco implementation you might find Model.Content.GetPropertyValue<string>(“subTitle”) to write out a property value in a template, or Umbraco.Field(“subTitle”)... or if you have sites like our ‘old friends’... a mixture of both! In the same template!

In V8 the syntax has become Model.Value<string>(“subTitle”) much simpler! Much more understandable, but different, and luckily in many places ‘Find and Replaceable’…

… but not in all cases, there is a new FallbackTo: methodology and across a large site there might need to be some post Regex Replacing manual intervention.

If your site uses WebForms then yes, reimplementing templates is the way to go, but what if you’ve got a fairly solid MVC implementation using the latest-ish V7 templating methods? ...do you really need to make this big re-implementation leap, all in one go? are there any smaller steps we could take to reduce the Umbraco V8 migration gap?

Umbraco 8 - Bridging the gap

Our solution to this seemingly intractable situation (small steps vs big bang) to try to bridge the migration gap is to create a temporary V7 'bridging dll'... and since it’s a ‘temporary bridge’, and well, because Marc has named it…  it’s called the UmbracoV7Pontoon.dll …

The temporary bridging dll implements some of the most common old PublishedContentExtensions and Umbraco Helpers that have had their syntax changed or functionality removed in V8 eg:

When you drop the V7Pontoon dll into a migrated V8 site (and replace Model.Content. with Model. with one global replace), and add a reference to its namespace all the V7 implementations for GetPropertyValue and Umbraco.Field  magically ‘work again’... which in turn enables ‘whole pages’ to work again in the migrated V8 site. The big win is not so much that 'things work' but that it’s now much easier to find and focus on the parts of the site that are more seriously broken by the migration… distinguish quickly between trivial syntax changes and actual problems, which a big-bang approach would not quickly uncover.

Now the idea here isn’t necessarily to never update the syntax, and to ship a migrated ‘big bang Upgrade Now to V8' implementation with the V7Pontoon permanently in place… but it does give you options, particularly when evaluating effort involved in a migration and buys you time to make incremental decisions… eg maybe a section of the site will be replaced in the next three months anyway… why spend time and budget changing the syntax now?

All new development can follow the new V8 syntax, sections can be ported across incrementally over time, and the V7Pontoon bridge removed whenever the work is complete… 

Useful in V8 Template Refactoring

Even if you are 'all in' on a big bang 'reimplement of all the templates' approach - The UmbracoV7Pontoon can still provide assistance during the refactoring...

… since we have decorated the methods of the V7Pontoon as Obsolete!

Eg

[Obsolete("object GetPropertyValue(alias, defaultValue)is obsolete, use Value(alias, fallback: Fallback.ToDefaultValue, defaultValue: default) instead.")]

This provides several useful outcomes when refactoring…

1. In Visual Studio, you get a helpful squiggly green line under any obsoleted method in use in a template, so it’s easy to spot that the syntax here needs updating.
2. You get a useful message from the Obsolete decoration telling the developer exactly what the new equivalent approach is to replace the old syntax - without the developer having to leave the context of the template to check...
   
3. When you build the solution in Visual Studio, with intellisense + build warnings on, you’ll get a list of all the obsoleted code that is still used, in one long list...

… acting like some kind of ‘To Do’ list for migrating and refactoring the syntax changes across the whole site. Measuring how many are left - double-clicking one will take you to the code (take you to the bridge!), and also the list gives you an indication for when it’s all done and it's safe to remove the Umbraco V7 Pontoon dll once the Obsolete warnings have gone.

The strategy reduces the risk of migration errors, helps developers comprehend the new syntax changes, and pragmatically reduces the steps absolutely necessary to migrate to V8.

If you want our help in migrating from v7 to v8 and to take advantage of our ‘pontoon’ and other migration tips and strategies from over the years, then why not get in touch. contact@moriyama.co.uk