Skip to main content

Upgrading to Umbraco 14 Preview

By

This is one of a series of posts looking at migrating Umbraco packages to Umbraco 14 and the new backoffice. Other posts in this series:

  1. Introduction
  2. Upgrading to Umbraco 14 Preview
  3. Creating a Property Editor With Umbraco 14
  4. Adding and Deleting Criteria

Prerequisites

As indicated in the official documentation, to work with Umbraco 14 it's likely your development machine needs some updates, which was the case for me. You'll need:

Package Update

The package I'm working on consists of a solution containing couple of projects, with most C# code in a "core" project which is depended on by the installable package project that holds the front-end code. There's a test project and several example Umbraco sites, for 9, 10, 11 and 12. I've been fortunate in that I haven't run into any breaking changes migrating from 9 to 12, and as such there's only one version of the package, that depends on Umbraco 9, but works across 10, 11 and 12 too.

In a new branch I've removed the test sites and then made the following updates to migrate to Umbraco 14.

Firstly, added a NuGet.config file in the root of the solution such that I can reference the Umbraco prerelease feed.

In the .csproj files I updated the TargetFramework setting from net5.0 to net8.0.

And I updated the CMS dependency version from to [9.0.0, 13) to 14.0.0--preview003.

Crossed my fingers and rebuilt... and it compiles! So no breaking changes moving up to Umbraco 14 either. Well, none in the C# code anyway...

Creating an Umbraco 14 Test Site

I then wanted to add back a test site for Umbraco 14. To do this I ran the following:

dotnet new install Umbraco.Templates::14.0.0--preview003
dotnet new umbraco -n TestWebApp.V14

Having added the resulting project to the solution I then took a project dependency my package, and tried to build again. This time I hit an issue - an error of The fully qualified file name must be less than 260 characters. Specifically: 

C:\Users\abutl\.nuget\packages\umbraco.cms.staticassets\14.0.0--preview002\staticwebassets\umbraco\backoffice\packages\core\property-editor\uis\collection-view\config\bulk-action-permissions\property-editor-ui-collection-view-bulk-action-permissions.element.d.ts exceeds the OS max path limit.
The fully qualified file name must be less than 260 characters.

Fortunately this is a Windows limitation that is fairly easily fixed by tweaking a registry setting to enable long path support. You can do so by running this Powershell:

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
    -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

After a Visual Studio restart, the build now succeeds.

Migrating from an Umbraco 12 Database

The next step I tried was to run the Umbraco 14 site, whilst connected to the database from my test site for Umbraco 12. Accessing the backoffice to start the migration leads to an issue though: Invalid object name 'umbracoOpenIddictApplications'.

It looks like there's a catch-22 here - to login and run the migration we need some tables to exist, but these tables need to exist to login. I think this wouldn't be an issue if I had migrated through Umbraco 13, but in any case have raised this as an issue on the tracker.

There's a workaround - just use the unattended install options.

This works to run the migrations but there looks to be an issue with one of them:

BootFailedException: Boot failed: Umbraco cannot run. See Umbraco's log file for more details.
Umbraco.Cms.Core.Exceptions.BootFailedException: An error occurred while running the unattended upgrade.
The database configuration failed with the following message: The given key 'ID' was not present in the dictionary.

Tracing this through indicates something not working correctly with one of the migration steps named AddGuidsToUserGroups. Again I've raised this on the tracker so hopefully it'll be quickly resolved, but in the meantime I got around this by running a SQL script that does what the migration attempts to, which I'll share below:

ALTER TABLE umbracoUserGroup
ADD [key] uniqueidentifier NOT NULL DEFAULT NEWID()
GO

CREATE NONCLUSTERED INDEX IX_umbracoUserGroup_userGroupKey ON dbo.umbracoUserGroup (
	[key]
) WITH( STATISTICS_NORECOMPUTE = OFF, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS = ON, ALLOW_PAGE_LOCKS = ON) ON [PRIMARY]
GO

UPDATE umbracoUserGroup SET [key] = 'E5E7F6C8-7F9C-4B5B-8D5D-9E1E5A4F7E4D' WHERE userGroupAlias = 'admin'
UPDATE umbracoUserGroup SET [key] = '9FC2A16F-528C-46D6-A014-75BF4EC2480C' WHERE userGroupAlias = 'writer'
UPDATE umbracoUserGroup SET [key] = '44DC260E-B4D4-4DD9-9081-EEC5598F1641' WHERE userGroupAlias = 'editor'
UPDATE umbracoUserGroup SET [key] = 'F2012E4C-D232-4BD1-8EAE-4384032D97D8' WHERE userGroupAlias = 'translator'
UPDATE umbracoUserGroup SET [key] = '8C6AD70F-D307-4E4A-AF58-72C2E4E9439D' WHERE userGroupAlias = 'sensitiveData'
GO

With this database update, the migration step is skipped over, allowing the migration plan as a whole to run to completion.

And with that, we have a backoffice!

Labels:

Comments

Post a Comment