The Method4 Umbraco Migrator allows migrating content and media from an Umbraco v7/v8 site to an Umbraco v10+ site.
This tool was originally created as an internal tool for us at Method4, to make migrating our client's Umbraco sites easy, and we've decided to make it available as an open-source package; as we believe other devs in the Umbraco community may find it useful too.
The migrator tool consists of 2 packages:
Generates the Migration Snapshot .zip files that will be imported into your shiny new 10+ site!
Imports the migration snapshots and runs mappers to transform the data.
The Target package ships with built-in default mappers that perform "lazy" mappings, e.g. if an old Node's DocType matches one of our new DocTypes it will attempt to map it, and if any of its properties have identical aliases, then their raw values be copied across.
- Migrate a node if its old DocType alias matches one of the new DocType aliases
- Migrate a property if its old alias matches one of the new property aliases
- The raw property value will be copied across
- it will also attempt to convert the format if the new data type has been updated to a new version
- E.g. MediaPicker (legacy) can be converted to the new MediPicker 3's format
If you need to perform any transformation logic on any of the doctypes/properties, e.g. if a doctype has changed alias, or a property has changed data type, then you will need to create some custom mappers implementing our IDocTypeMapping/IMediaTypeMapping interfaces.
When a migration snapshot is imported, a lookup table is populated with the old node IDs and Keys (from the source site) alongside the new IDs and Keys (generated by the target site); This means that future migration snapshots will simply update the previously migrated nodes, rather than creating new nodes, when imported.
This allows you to continue editing content on your source site, all the way up until you perform your final migration!
The package ships with built-in default mappers that perform "lazy" mappings, e.g. if an old Node's DocType matches one of our new DocTypes it will attempt to map it, and if any of its properties have identical aliases, then their raw values be copied across.
You can also define custom mapping logic by implementing our IDocTypeMapping/IMediaTypeMapping interfaces, read the documentation for more information.
MediaPicker (legacy) can be converted to the new MediPicker 3's format automatically, or by using our helper classes.
The Package's major versions will match the minimum compatible Umbraco version.
Whilst this does go against semantic versioning, it should make it easier to figure out which version will work for you.
We'll try to keep breaking changes out of minor versions, but they may happen if we need them.
| Umbraco Version | Package Version |
|---|---|
| v10, 11, 12 | v10.x |
| v13 | v13.x |
To install from NuGet, you can run the following command from the dotnet CLI:
dotnet add package Method4.UmbracoMigrator.Target
Documentation can be found in the /docs folder, and there are examples of custom mappers in the /custom_mapper_examples folder.
You will need to install the Method4.UmbracoMigrator.Source package onto your source website, to generate the snapshots.
This package was originally created as an internal tool for us at Method4, to make migrating our client's Umbraco sites easy, and we've decided to make it available as an open-source package; as we believe other devs in the Umbraco community may find it useful too.
The package will be updated as and when we need it, feel free to report any bugs/issues you find, contribute by opening a pull request, and we will take a look when we have capacity. Please read the Contributing Guide for information on how to set up the project locally.
Please see the roadmap for a list of outstanding features and TODOs.
Copyright © Method4.
All source code is licensed under the Mozilla Public License.
- Owain Jones - (GitHub, Mastodon, Twitter)
The package logo uses the Local Shipping icon from Google Fonts, licensed under SIL Open Font License.
If this package doesn't fit your needs, then check out these other awesome community packages: