Kevin Jump

Posted on Sep 27, 2023

uSync to v14 - part 1/n

Upgrade Log:

This is a rough upgrade log of uSync from Umbraco 12 to Umbraco 14 (at some point merging any Umbraco 13 sizzle).

You are free to read along with me, but this isn't advice, best practice or anything its me working through a project and learning as i go)

Master blog for all the entries

It's things that happen as I go, We are not yet "full time" on this update, so things happen we might scrap start again, etc.
But lets see how we go.

Aims:

Get it building.
Get some UI (not necessarily working)
Refactor the controllers to use the new management API
Workout how to link services to new UI a. Link the services to the new UI
Get a working UI
Work out what other things we need to fix (e.g Newtonsoft will need replacing)

Code is on this branch : https://github.com/KevinJump/uSync/tree/v14/convert

Day 1: 27/09/2023

https://github.com/KevinJump/uSync/commit/3b13b4ceff21ef627c44073797870892996403c5

Fork the repo.
Remove the uSync.Site
Update all the csproj files to .net 8 - 14.0.0--preview003 of Umbraco.
Remember our gulp script in a build (it will be removed soon) npm install
Disable package validation (this is a new version)
Unload test (until we are building)

Now we are getting umbraco errors !

Time to work out where the cheese have been moved to:

Datatypes.
- .Configuration is now either ConfigurationObject or ConfigurationData, except ConfigurationDate is writable (dictionary) – this is likely going to lead to a format change?
- We use to serialize the object here, I am guessing that was causing issues so its been simplified in the core
Languages
- All the warnings that are v12 about things changing are changed (there is no soft migration here – so it’s a question of changing them)
  - FallBackLanguageId => fallbackLanguage
  - Usynvc already syncs the iso not the id, so actually this make the code simpler for us. One less language lookup.
Dictionaries
- Similar translation.language.isocode has now become languageIsoCode
ContentTypes
- Allowed Content Types – that’s now storing key not id.
Manifest filters have gone! (which is to be expected the new UI replaces all of this)

*30 mins in – it compiles. *

(no ui and not yet linked to a v14 site) but the code using Umbraco preview and running on .net 8.0

Add dependency in our v14 site to the main uSync project (that then contains all the others)

Build… run … no errors.

Site has a usync folder 🤯(this site has no content at the moment, so its only got basics datatypes, doctypes in it)

Here’s where it becomes hard.

Added a new doctype, added structure and some settings, saving ‘Bad request’ is that uSync or is it the preview ?
Looks like doing too many things at once (e.g adding allow root and setting structure) can cause ‘bad request’ on the preview (003).

I don’t think I can create content on preview-003 🥲

The default uSync page for an empty site still works 😊

OK – time to new UI.

New Razor class library. (uSync.Backoffice.Nu.Assets)
Then following https://docs.umbraco.com/umbraco-backoffice/extending/development-flow/vite-package-setup o Creating a new ‘uSync’ project



npm create vite@latesst -- --template lit-ts uSync
cd uSync
npm install
npm install -D @umbraco-cms/backoffice
new vite.config.ts,

but – change outDir to ../wwwroot/uSync

This means the project builds into my razor class libraries wwroot folder which in turn is going to be my projects app_plugins folder.

In my public folder, create the umbraco-package.json file (this will then get put in the wwwroot/uSync folder on build.

Still following the ‘create a custom dashboard’ tutorial here. https://docs.umbraco.com/umbraco-backoffice/tutorials/creating-a-custom-dashboard

Change the main uSync project dependency to point to my new assets package.
Build… release that I have yet to put any vite build stuff into my csproj, so



npm run build -- –emptyOutDir

then build the solution.

Things to fix:

Pack to the file was wrong (was /app_plugins/dist/something, I am writing direct to /app_plugins/uSync/usync.js
The default dashboard code doesn’t work for me, getting some js errors
(the other dashboard example does work).

Things to note:

Changing umbraco-package.json requires a site restart
Changing the js – doesn’t (once its built) as the RCL file change causes the site to reload.
I suspect some form of watch command would make this all streamlined.

Just lost 4 minutes to a umbraco-package.json typo



"conditions": [
  {
    "alias": "Umb.Conditions.SectionAlias",
    "match": "Umb.Section.Settings"
  }
]

Extra s in Umbraco.Conditions.SectionAlias – no errors for this, it just doesn’t work until you spot it. (There are lots of ‘known strigs all over this config now, type them wrong and you will be lost with no warnings or errors)

Add the new site boot screen in to uSync.BackOffice.Nu.Assets ( create the app_plugins/uSync/boot folder wit the files)

This means the assets package has to have a dependency on Umbraco and uSync to render the page.

Slightly different because of the build process. The main cshtml file goes in /app_plugins/uSync/boot/ but the assets (css and image) have to live in the public folder so vite copies them to /wwwroot/usync/boot. – bit odd but it works fine.

Back to UI :

Trees are not documented yet – so it will have to be a code deep dive on how to configure a tree.

Time to download a copy of the Umbraco v14 source !

Cloning v14/dev fails because of a sum module. Lets just download a zip !

Of course that’s not the one with the back office in, it’s in umbraco.cms.backoffice

https://github.com/umbraco/Umbraco.CMS.Backoffice

The core source doesn’t use the umbraco-package.json format, it is declaring them as manifest classes inside the modules. I suspect these are very similar but not parsing the json makes it a bit quicker.

Just had a quick google to make sure I wasn’t missing some docs or something for this somewhere else.

The Backoffice story book – has lots of info https://apidocs.umbraco.com/v14/ui/?path=/docs/guides-extending-
the-backoffice-intro--docs will be interesting when we are customzing out the dashboard,

but nothing on the config (I think)

I’ve relaised my itellisense wasn’t working for the schema, because the schema file is in the website project, and I am in a assets project, adjusted the path, so it
Now reads it. Now I have wobbly lines!
(also would have caught my typo from before)

Got a little bit confused there because I forgot to npm run build and was rebuilding in visual studio and nothing changed.
Will need to get some better built trigger /watching sorted next time.

After some code looking I have:

1. A section :



{
   "type": "section",
   "alias": "uSync.Section",
   "name": "uSync Section",
   "weight": 450,
   "meta": {
     "label": "Syncronisation",
     "pathname": "usync-section"
   }
 },

_but I don’t need a section ? _

2. The "section" for a tree :



{

   "type": "sectionSidebarApp",

   "kind": "menu",

   "alias": "uSync.Menu",

   "name": "uSync sidebar menu",

   "weight": 200,

   "meta": {

     "label": "uSync",

     "menu": "uSync.Menu"

   },

   "conditions": [

     {

       "alias": "Umb.Condition.SectionAlias",

       "match": "Umb.Section.Settings"

     }

   ]

 }

Day 1 - summary

Not bad for a little over 2 hours, it builds, i need to get some of the UI sorted, but the docs are missing, so if i carry on from here its source code mining time.

I don’t really want the section, next time I need to workout how to get the actual menu items beneath the uSync section.