Skip to main content
Version: v17.x - Umbraco 17

uSync.Migrations

Not Supported

Migrations can be varied and complex, and while we have developed uSync.Migrations, we cannot support individual migrations. The code is open source, and if you have any issues we encourage you to contribute.

warning

If you have a fairly modern Umbraco v10+ site, with no legacy data providers (e.g Grid or Nested Content), You don't need uSync.Migrations! Standard uSync will perform the minor updates between current properties and content inline, without you needing to do any fancy upgrades.

Migrations is only really necessary when you want to go from one property type to another (e.g Grid to BlockGrid).

uSync.Migrations is your way to migrate an older version of a site to a new one

You can easily put the files on the site, press the upgrade buttons, and get an upgraded site out the other side, and You can still customise and extend migrations to your hearts content!

uSync.Migrations will look for old version folders (e.g /uSync/v8, or /uSync/v13). You can copy the uSync folder from an old site into a new sites version of uSync directly and migrations will pick it up.

Migrating from the Grid

When you are migrating from the grid, we reccommend you put the sites config folder into the versioned uSync folder (e.g /uSync/v8/config). This will mean that Migrations can read the grid settings from the old site and ping them over.

Installing uSync.Migrations​

uSync.Migrations rc1 requires uSync v17.1.0-rc1 to work.

dotnet add package uSync.Migrations --prerelease

What is uSync.Migrations Doing?​

uSync will migrate a lot of things for you. Migratrions can also migrate.

  • Nested Content to BlockList
  • Grid to BlockGrid
  • Macros to Content Types (including updating the content)
  • Swicher to toggle
  • SpecrumColurPicker ... and loads of community migrations from v4!

In version 17 there are three steps to migrating.

Step 1: Analyse​

First, uSync.Migrations will look at the files in your legacy folder. If there are any issues, it will be reported to you.

Step 2: Upgrade​

Next, uSync.Migrations will create any new content type or data type uSync files that might be needed for the data to be migrated.

For example, new content types for all the grid elements, or new content and doctypes to replace any macros you might have defined.

Step 3: Import​

Finally, it is time for the import! This is the same as the standard import uSync performs. Migrations does have some extra items that integrate with the standard import, such as ConfigSeriaizers and ValueMappers. Anyone can write these, and they will run on import.

The import will run some things through twice. This is because, for example, the Grid DataType requires that all the new content types be created, and rather than write a whole new import process, we run it twice.