How to migrate an Orchard 1 application to Orchard Core
How long have you been using Orchard 1 for your website? How satisfied are you with its features and performance? Have you encountered any limitations or challenges with Orchard 1 that you hope to address? If you are looking for a modern and improved version of Orchard 1, you might want to consider migrating to Orchard Core which is a better version of Orchard 1 in many aspects. Orchard Core is not just a port of Orchard 1, but a new and improved system that offers many benefits over its predecessor.
What are the benefits of migrating to Orchard Core?
You can enjoy numerous remarkable benefits by migrating to Orchard Core.
First of all: Performance. As the saying goes: “The faster the better.” Orchard Core is so fast that an output cache module like for Orchard 1 is not required. For example, you can set up a site with the blog recipe in less than half the time that Orchard 1 needs for the same task.
It is portable: it can run on Windows, Linux, and macOS, as well as on Docker containers.
It has a more flexible and extensible modular framework that allows building modular and multi-tenant applications more easily. Orchard Core also supports NuGet packages for modules and themes, thus creating a new website with it is actually as simple as referencing a single meta package from the NuGet gallery.
It is built on ASP.NET Core. This means that it can use any C# language version without any limitations, while Orchard 1 uses .NET Framework 4.8 which means it’s restricted to C# 7.3.
It has new features that are not available in Orchard 1, such as GraphQL API, OpenID Connect, Liquid templates support, and more.
It supports all major site building strategies: Full CMS, Decupled CMS, Headless CMS.
This is just the tip of the iceberg, to read more about Orchard Core check out its documentation.
Preparations
The first thing to know is that there is no easy or fully automated way to migrate your website and content. The two systems are different in terms of data schema, modules, themes, and features. However, in general, we can say, that proficiency in Orchard 1 puts you in a good position to develop in Orchard Core too. There are a lot of similarities for example menu points on the admin UI, or how migrations work, etc.
A good first step would be to take a look at your current application. Do you want to replicate what you have there, or do you also want to improve it? Migration is a good opportunity to renew your site, change design, and functionality, get rid of obsolete elements on the site, etc.
You'll also need to know Orchard Core before attempting a migration. If you are new to Orchard Core development, we recommend that you start with our Dojo Course 3 - the full Orchard Core tutorial. This course covers the fundamentals of Orchard Core for both users and developers.
New CMS, familiar features
Before starting the migration, it is recommended to check your most used, most important features in Orchard 1 and list them. There is a good chance that there is an equivalent feature in Orchard Core, but it changed and has been upgraded, so you will need to do some research.
For example, if you want to migrate your custom form, instead of Orchard.DynamicForms you can use OrchardCore.Forms to achieve the same result. Or instead of Orchard.Taxonomies you can use OrchardCore.Taxonomies. The Workflows and Audit Trail modules were ported to Orchard Core and improved too.
Migrating content types
Content types are composed of content parts and fields, which provide different functionalities and data types for your content. If you want to migrate your content types, you will need to recreate them in the new system. Luckily, as with features most of Orchard 1 content parts and fields have their equivalent in Orchard Core. Some examples are BooleanField, NumericField, TitlePart, or CommonPart. In this case, you can recreate your content type from the admin UI, from a recipe, or with a migration.
Let’s say you have a BlogPost content type in Orchard 1, which has the following parts and fields:
-
TitlePart: Provides a title for the blog post.
-
AutoroutePart: Provides a URL for the blog post.
-
BodyPart: Provides a rich text editor for the blog post content.
-
MediaLibraryPickerField: Provides a way to select an index image for the blog post.
Now take a look at what we have in Orchard Core. We have TitlePart and AutoroutePart in Orchard Core too, so that is handy, but there is no BodyPart and MediaLibraryPickerField. But after some research, we can find the equivalent of them: HtmlBodyPart and MediaField.
We have all the parts and fields in the new CMS to recreate the BlogPost content type. In this example, we are creating it with the help of a migration file BlogPostMigration.cs:
using OrchardCore.Autoroute.Models;
using OrchardCore.ContentManagement.Metadata;
using OrchardCore.ContentManagement.Metadata.Settings;
using OrchardCore.Data.Migration;
using OrchardCore.Html.Models;
using OrchardCore.Media.Settings;
using OrchardCore.Title.Models;
namespace MyProject.Migrations;
public class BlogPostMigration : DataMigration
{
private readonly IContentDefinitionManager _contentDefinitionManager;
public BlogPostMigration(IContentDefinitionManager contentDefinitionManager) =>
_contentDefinitionManager = contentDefinitionManager;
public int Create()
{
// Define a part called BlogPost with some fields.
_contentDefinitionManager.AlterPartDefinition("BlogPost", part => part
.WithField("Image", field => field
.WithDisplayName("Index Image")
.WithPosition("0")
.WithSettings(new MediaFieldSettings
{
Multiple = false,
}))
);
// Define a type called BlogPost with some parts.
_contentDefinitionManager.AlterTypeDefinition("BlogPost", type => type
.DisplayedAs("Blog Post")
.Creatable()
.Listable()
.Draftable()
.Versionable()
.Securable()
// Add the Title part to provide a title for the blog post.
.WithPart(nameof(TitlePart), part => part
.WithPosition("0"))
// Add the BlogPost part to provide some fields for the blog post.
.WithPart("BlogPost", part => part
.WithPosition("1"))
// Add Autoroute part and configure it to use a pattern based on the title.
.WithPart(nameof(AutoroutePart), part => part
.WithPosition("2")
.WithSettings(new AutoroutePartSettings
{
Pattern = "{{ ContentItem | display_text | slugify }}",
}))
// Add the HTMLBody part to provide a rich text editor for the blog post content.
.WithPart(nameof(HtmlBodyPart), part => part
.WithPosition("3")
.WithEditor("Wysiwyg"))
);
return 1;
}
}…and don’t forget to add your migration to the Startup.cs file to register it.
However, if you have a content type with custom fields and parts, with custom functionality, and features, you will also have to recreate those fields and parts by reimplementing your custom code in the new project.
Migrating content items
The best way to add numerous content items is with a recipe. To migrate the content items, first, make sure that you have the content type created in the new system. After that, you will need to export your content items. The file formats of the recipes are different in the new CMS: Orchard 1 uses XML, while Orchard Core uses JSON, however, their functionality and use cases are similar.
You will need to create an Orchard Core recipe: This can be done either manually, or Lombiq has a feature for this in the open-source Helpful Extensions module called Lombiq Helpful Extensions - Orchard 1 Recipe Migration. It has built-in functionality for content items with the most used content parts, but you can extend the built-in functionality to support more parts.
Conclusion
Migrating from Orchard 1 to Orchard Core is a challenging but rewarding process that can bring many benefits to your site. However, it requires careful planning, preparation, and testing to ensure a smooth transition.
We have extensive experience and expertise in migrating sites from Orchard 1 to Orchard Core, and we can help you migrate your project. Lombiq has recently renewed and migrated its main site http://lombiq.com to Orchard Core too, and we are very happy with the results. You can check out our site and see how Orchard Core can power your site too. Happy migrating!
stephi said
Thanks for the article. Please compare Elanat framework with orchard in an article.
Zoltán Lehóczky said
I don't think we could dive sufficiently into Elanat to be able to provide a fair comparison, but if you have any specific questions that would help you, please just ask!