Migrating to Serenity.NET 5

Serenity 5 is a major update to Serenity Framework. It only supports .NET 5 and ASP.NET Core 5. For those who missed the news, .NET 5 is actually .NET Core 5, and is simply called .NET now. They skipped version 4 to avoid confusion with legacy .NET Framework 4.

Introduction

From this point on there will only be an .NET 5 / ASP.NET Core 5 version of Serenity / Serene and StartSharp. As announced about six months ago (https://github.com/serenity-is/Serenity/issues/5060) we are no longer supporting .ASP.NET MVC or .NET Framework 4.5. There is a v3 branch in Serenity, Serene and StartSharp repositories but we will not be releasing any new versions there unless we find a critical security issue or similar. Anyway if we release a version there, it will be 3.x not 5.x.

Background

When we first released .NET Core version of Serenity initial target was to provide easy migration and code compability between ASP.NET MVC and ASP.NET Core templates, so that we could easily share code between two. For example, if we added a new sample to ASP.NET MVC, it had to be easily portable to .NET Core version with as few changes as possible. At that time, .NET Core itself was at its early stages, had some issues, missed some features and was not so stable. So the main branch of development for Serenity was still ASP.NET MVC. This changed in the last year, as we started to develop new features in .NET Core and ported them back to .NET MVC afterwards. Also, most of our customers we directly worked, ported their projects to .NET Core.

As the initial target was compability between two, we could not use some features of .NET Core like, primary one being dependency injection at the start. By time it became a pain source, as it is very important for testability and integration with the .NET Core platform itself.

List of Changes

We decided to completely embrace .NET Core / ASP.NET Core features, and use them instead of the ones in Serenity where possible, so there are many changes:

This is not a complete list but should provide an overall idea.

Serenity 5 Packages

The Serenity 5 packages are prefixed with ".Net", to prevent confusion with v3 packages, and also to avoid users who still use v3 or ASP.NET projects to upgrade by mistake. Here is a list of Serenity 5 packages, and their original names in v3:

Upgrading to Serenity 5

The recommended way to use Serenity 5 / .NET 5 is to download latest StartSharp template, and create a new project.

For existing projects that you would like to port to .NET 5, you'll need to follow steps outlined in:

If you haven't yet migrated your project to .NET Core, first follow steps here: https://serenity.is/docs/migration/mvc-to-core

For StartSharp customers, who recently created a project using the prior 3.14.5.6 (or a recent one) we prepared a tool called stargen to make migration easier.

See this document for information about stargen and using it to migrate your project.