Weekly Commit #013

Back after a week off, and the task waiting for me was a big one: upgrading from Umbraco 13 on .NET 8 to Umbraco 17 on .NET 10. Four major CMS versions and two runtime versions in a single jump.

Drawing the plan first

My first step was to draw up a plan. I started reading some articles online and came to the conclusion that first of all I would need to upgrade to the latest version of Umbraco 13, and only after that make the real jump to Umbraco 17, stepping through each major version along the way.

Most of what followed was exactly the grind I expected. 600+ compile errors as APIs moved or disappeared, generated models that no longer built, backoffice controllers that had to be ported to a completely new management API, and so on. Tedious, but mechanical. The compiler tells you where to go.

The part no compiler could catch

After everything built and the site booted, the database migration failed when trying to upgrade from 15 to 16. Umbraco ships a migration that rewrites some default constraints, and it looks them up by name, expecting the DF_table_column convention that SQL Server normally generates. Ours didn't match.

The code was fine. The migration was fine. The environment was subtly different from the one I assumed. A colleague had even warned me about this, because he was responsible for the previous jump to v13, and still nothing surfaced it until a migration reached in expecting a name that wasn't there. The fix was renaming 23 constraints by hand so the convention lined up.

Smaller things this week

I wrote a migration composer that simply never ran. No error, no log, nothing. It turned out the framework only discovers composers in certain assemblies, and mine was in the wrong project. Moved it one project over and it fired immediately.

A PowerShell script I used to bulk-edit generated models quietly corrupted files full of accented Portuguese characters, because Set-Content without an explicit encoding doesn't preserve UTF-8 the way you'd hope.

An icon package we depended on didn't work on v17, so all the icon rendering broke. Each icon data type stores its own mapping in a config JSON, so I rebuilt the rendering by reading that JSON at runtime and resolving each icon from there myself.

Something I read this week

The chapter on consistency in John Ousterhout's A Philosophy of Software Design. Given how my week went, the timing was funny: I was reading about why conventions matter exactly as a broken one was quietly costing me half a day.

Thirteen weeks in

Last week I didn't post because I was off, but now I am back. The lesson that stuck: the errors a compiler can catch are the cheap ones. The expensive ones live in the gap between the environment you assume and the one you actually have. See you next week.