Migrate your project
Migration commands
You use the migration commands to migrate front-end resources (pages and page templates), written in Web Forms or MVC, to a decoupled renderer architecture based on ASP.NET Core.
The following commands are available:
sf migrate page "PageId"
Migrates a page.sf migrate template "TemplateId"
Migrates a page template.sf migrate help
Prints online the same help as this article.
IMPORTANT: The Sitefinity CLI tool helps you migrate only the content and structure of the page templates and pages. You still need to re-implement all custom widgets you are using on your site.
The migration tool is not a complete solution and can generate warnings or incomplete front-end resources. You are responsible to check its results.
IMPORTANT: The migrate command supports migration only from Web Forms and MVC widgets to ASP.NET Core widgets.
PREREQUISITES: The migration commands only support projects based on Sitefinity 15.3 and higher.
General flow of migration
RECOMMENDATION: We recommend to analyze and evaluate the state of your Sitefinity project and to estimate the resources needed for migration before starting the migration itself.
For more information, see
Technology migration.
To migrate your Sitefinity CMS project, perform the following procedure:
- Start with the migration of templates that a subset of pages is based on OR migrate all of the page templates at once.
- Make adjustments to the migrated structure as needed.
- Set a file system template.
- Migrate the widgets used on the template.
- Take a business decision if you can stop using some of the existing widgets. For example, drop widgets if the business need is no longer there.
- Manually configure the widgets that are migrated.
- Make adjustment to the look and feel of the page.
-
Once you complete the migration of the chosen page templates, move on to the pages structure.
- Sitefinity CLI duplicates the Pages by default and excludes the copies from the navigation.
- Once you fully migrate the page, specify the
--replace option to the CLI migrate page command.
NOTE:
- You can specify the
--replace option only when the page has a duplicate.
- The CLI uses the page's
UrlName property OR the page template's Name property to identify the page or the page template that it created. The format has a suffix of (migrated to Decoupled). This process avoids conflicts with existing pages and page templates.
- The CLI uses only data from the published pages and page templates.
Draft and Temp changes are not migrated.
- Sitefinity CLI automatically migrates forms if there is a form widget on the page.
Migrating hierarchies
- When you select a page template, the CLI migrates first the parent page templates. Migration cannot happen otherwise.
- If parent page templates are migrated automatically, they will be also published automatically.
NOTE: When migrating pages, the CLI will not migrate the parent page templates. You must migrate all dependent page templates before migrating pages.
Safe box & Testing
All pages and page templates are duplicated by default with a suffix (migrated to Decoupled) appended to the their Title. This provides a level of isolation for existing pages and page templates, so that the migration can happen seamlessly and without downtime. This is a great way to test the changes before they go live.
NOTE: When migrating pages, you can use the option --replace. This option replaces the page contents on the actual page and saves the page automatically as a Draft, regardless of the value of the --action option.
This option keeps the existing links from content blocks, html fields, and related data and you do not need to update these references.
NOTE: Duplicated Pages are hidden from navigation by default.
CLI command-line parameters
Required parameters
The following CLI parameters are required.
--cmsUrl
The URL of the deployed Sitefinity CMS.
For example, https://www.example.com/en
--token
The authentication token to use.
To learn how to generate a token, see Generate access key. You must use a token of an account with full Administrator privileges.
Optional parameters
The following CLI paramaters are optional.
--recreate
Recreates the selected page or template and its parent templates.
Useful when testing and experimenting with custom configurations/custom widget migrations.
--recursive
Recursively migrates all the child pages or templates of the selected page/template. When migrating templates, the tool does not recursively migrate pages.
--replace
Replaces the content of the page. Valid only for pages.
--action
The action to execute at the end of the migration. Allowed values are:
draft - Save the migrated resource as a Draft.publish - Publish the migrated resource.
--siteid
The site id. You use the --siteid parameter to specify the site id when you work with a non-default site.
NOTE: You can set the parameters manually in the appsettings.json file. You need to manually create the appsettings.json file next to the sf.exe binary.
You can mix both appsettings.json parameters and direct command-line parameters, with the latter having precedence.
EXAMPLE: Following is an example appsettings.json file.
{
"Commands": {
"Migrate": {
"CmsUrl": "http://localhost",
"Token": "TOKEN",
"Recreate": false,
"Recursive": false,
"Replace": false,
"Action": "publish",
"SiteId": "00000000-0000-0000-0000-000000000000",
"Widgets": {
"Telerik.Sitefinity.Modules.GenericContent.Web.UI.ContentBlock": {
"Name": "SitefinityContentBlock",
"Whitelist": ["Html", "ProviderName", "SharedContentID"],
"Rename": {
"Html": "Content"
},
"CleanNullProperties": true
}
}
}
}
}
Widget migration
You can migrate widgets in two ways - using configuration and using custom widget migrations.
Migration through configuration
You specify the migrations in the appsettings.json file.
EXAMPLE:
{
"Commands": {
"Migrate": {
...
"Widgets": {
"Telerik.Sitefinity.Modules.GenericContent.Web.UI.ContentBlock": {
// the name of the new widget in ASP.NET Core and Next.js renderers
"Name": "SitefinityContentBlock",
// the whitelist of properties to keep during the migration
"Whitelist": ["Html", "ProviderName", "SharedContentID"],
"Rename": { // the properties to be renamed
"Html": "Content"
},
"CleanNullProperties": true
}
}
}
}
}
Custom widget migrations
You can perform custom widget migrations when the configuration using the CLI is insufficient and a more complex logic is required. You use C# code to extend the functionality of the CLI itself.
You can reference the built-in widget migrations, located under the Migrations folder in the CLI source code.
Widget migrations are invoked for each occurrence of the widget found on the page or page template. For each invocation, a WidgetMigrationContext is passed. It contains:
SourceClient
The IRestClient for interfacing with the CMS.Source
The original widget, from which you are migrating.ParentId
The new parent id for the migrated widget.Language
The current language.SegmentId
The page segment when working with personalized pages.WidgetSegmentId
The widget segment when working with personalized widgets.LogWarning
Specifies a warning message to be shown in the Terminal during the migration of the widget.LogInfo
Specifies an informational message to be shown in the Terminal during the migration of the widget.SiteId
The site id. You use the SiteId parameter to specify the site id when you work with a non-default site.
A return value of type MigratedWidget is required as the output of the migration. It contains the new widget name and properties.
Helpful functions
From base class MigrationBase:
ProcessProperties
Copes and renames properties.GetMasterIds
Gets the master ids of the live content items (usually referenced in Web Forms widgets).GetSingleItemMixedContentValue, GetMixedContentValue
Helper for generating properties of type MixedContentContext.
Limitations
The CLI migration command does not migrate the code in any form. It can migrate only the content and structure of your project.
Migrating List widget to Content list widget
When you migrate a List widget (Web Forms, MVC) to a Content list widget (ASP.NET Core) and the existing widget shows two separate lists, the new Content list widget will show a single view, containing merged items from all original lists.
To show the multiple original lists separately, perform one of the following:
- create a new view to perform custom sorting and iterate the lists separately.
- use multiple separate Content List widgets, each configured to display only one of the lists.
Migrating Web Forms Image widget to Image widget
When you migrate a Web Forms Image widget with display mode set to Custom, the custom display setting is not migrated.
To work around, manually configure the image size through the widget designer.
Migrating Dynamic widget to Content list widget
When migrating a Dynamic content widget to a Content list widget (ASP.NET Core) and the main field is changed to a value different from the one in the Title field, you need to perform the following:
- Manually change the list mapping in the widget designer.
- Update the mapping for the
Details view in the ViewsMetadata.json file.
For more information, see Create custom views for the Content list widget » Field Mappings.
Migrating Blogs to Content list
Sitefinity CLI migration command does not support migrating Blogs widget (Web Forms, MVC).
You need to implement a custom widget in ASP.NET Core and manually migrate using this new widget. We recommend using the Content List widget (ASP.NET Core) to implement your custom widget.
Migrate Events widget to Content list widget
The new Content list widget (ASP.NET Core) comes with different predefined basic filter options than the MVC and Web Forms widgets.
Migration process transfers the old filters for past, current, and upcoming events into the Filter Expression field in Advanced mode of the widget designer.
Because of the difference in the filtering functionality between the different widgets, after the migration, you need to check the filters directly in the Filter Expression field.
If the filters expressions cannot be matched, you need to implement a custom widget in ASP.NET Core and manually migrate using this new widget. We recommend using the Content List widget (ASP.NET Core) to implement your custom widget.
Migrate Calendar widget
Sitefinity CLI cannot migrate the Calendar widget.
You need to create a custom widget, based on Content List widget (ASP.NET Core) to implement your custom widget.
Migrate Login form with Reset password mode set to Reset password widget
If you have configured the Login form widget (Web Forms, MVC) with Allow users to reset password to ASP.NET Core renderer, it is migrated without the option to reset the password because there is a separate widget providing that functionality.
You need to manually add the new Reset password widget (ASP.NET Core) on the page and configure it.
Replacement of multilingual pages
The following scenario is not supported:
- You migrate a page
- You add new languages only to the migrated copy of the page
- You attempt to migrate the page again, using the
--replace option
In this scenario, only the single original language of the original page is preserved.