How to Migrate from .NET MVC 5 to .NET Core for Kentico Xperience

Some Retrospects

The .NET Core and .NET 5 versions have been available for some time now. .NET 6 is the latest version of .NET that was released in Nov 2021.

.NET 6 

Many improvements have been made to .NET 6 over its predecessors, as well as some of the most incredible features that have been introduced to some of the most popular Java platforms and languages in recent years. 

As a truly unified development platform, .NET 6 allows developers to develop applications for cloud, web, desktop, mobile, gaming, the Internet of Things, and artificial intelligence within a single application. There are a number of sub-platforms that share a standard base class library, APIs, as well as underlying infrastructure, including the language and the compiler.

.NET 5

As a result of migrating to .NET 5, developers will be able to take advantage of a new cross-platform development experience. Consequently, it brings new unique features to the fragmented .NET universe. 

Some things to mention

There are two reasons why the name of this new release has been changed to .NET 5 instead of .NET Core 4:

• For clarity, version numbers 4.x have been skipped.

• The word "Core" has been removed from the name. 

Furthermore, .NET Framework 5.x will be the main implementation of .NET, but .NET Framework 4.x will still be supported. 

Returning to our central topic: how to migrate from .NET MVC 5 to .NET Core for Kentico Experience, Kentico MVC sites prior to version 13 were generally built using .NET MVC 5. However, at the time they were released, Kentico 11 and Kentico 12 MVC versions were not yet ready and basically had incompatibilities with .NET Core. 

Why Leverage .NET 5 (and .NET 6) There is no doubt that ASP.NET MVC Core, together with .NET 5, provides a compelling argument for almost every .NET-based application we have today. It might be hard for an inexperienced user to grasp the importance of .NET 5 as compared to .NET 4.x framework since the advancements are really, really, big. 

Before .NET 5, Kentico Xperience had traditionally run on .NET 4.x framework. 

ASP.NET 4.x continues to be used by NET developers for developing applications. It means that up till now, there are many applications with ASP.NET 4.x.  

Some features of .NET 5 framework

Compared to .NET Core 3.1, .NET 5 offers many improvements and new features. It's important to note that these updates are broken down by category and have a separate page for each update: 

1. updates for C#, F#, Visual Basic, and System.Text.Json; 

2. single file apps

3. app trimming

4. Windows Arm64 and Arm64 intrinsics

5.  dump debugging tooling and more.

Based on the recently released .NET Core 1.0 (Date of release - 2016) and 3.1 (Date of release - 2017) frameworks, .NET 5 is now the new future of the .NET framework and is the foundation to the future of the .NET platform.

Important note: There will be no .NET 4.7 or .NET 4.8 frameworks available for developers in .NET 5.

Our decision to use .NET 5 interchangeably with .NET 6 was based on the fact that both .NET 5 and .NET 6 versions have already been released. 

The following are some of the key benefits .NET 5 and .NET 6 offer when compared to Kentico Xperience (and other .NET apps):

• This release is performance-driven, and every release is getting faster and faster.

• The hot reload feature has been added to .NET 6 as a new feature designed to increase developer productivity.

• The framework is constantly being enhanced with new features, performance improvements, and security improvements.

• With the current framework, on the other hand, upgrading to .NET 6, 7, and so on can be done much more easily.

• A new version of Kentico Xperience can now be built and run cross-platform on any device (no need to install Windows or Visual Studio anymore).

• Enhancements to Blazor, a JSC# based interface builder for developing interactive websites (Blazor uses JavaScript instead of C#).

• There are faster loading and building of project files.

• The best practice here is Azure PaaS (of course).

• Open source on GitHub

• Support for minimal APIs

• Scripting with the CLI (Command Line Interface) and general usage.

• With .NET 6, you will receive additional years of LTS. 

Depending on the size of your application, or complexity of your Kentico installation, 

Cons of Kentico

The Kentico installation process can be quite complex, depending on the size and complexity of the website as well as the size and complexity of the installation itself. No matter how hard the work may be, as long as the benefits outweigh the effort, there can be no doubt that the effort is well worth it. Kentico only supports .NET 5 and .NET 6. The performance will be improved as a result. 

Let us get back to one of the main purposes of this post - and that is to come up with an overview of what we are going to do in order to migrate Kentico MVC 5 to Kentico .NET Core/ .NET 5 / .NET 6 in a smooth manner. 

The following are the general rules that should be followed when mitigating Kentico MVC 5 to Kentico .NET Core / .NET 5 in order to avoid problems in the future.

Migration & Steps 

There are a variety of rules for customizing and dependencies depending on the project, however, the general process for mitigating .NET 5 / .NET 6 vulnerabilities consists of the following steps:

Important: There are several steps involved in a .NET 5 / .NET 6 migration, but each has its own unique customizations and dependencies. Your migration may involve additional steps, but the general process is as follows:

Phase 1: Kentico Xperience Upgrade

The only version of Kentico Xperience that supports .NET Core / .NET 5 / .NET 6 is Kentico Xperience 13. The first and the foremost thing that you have to do is to make the upgrade to 13 with your Kentico admin tool. Ideally, you start out at Kentico 13. 

Phase 2: MVC Live Site Migration from MVC 5 to .NET 5 / 6

Kentico's official documentation does have very helpful steps that will guide you how to handle the very specific Kentico Xperience parts of the migration of Xperience from MVC 5 to .NET 5. You can use it as your future guidance. 

Step 1: Check Out .NET Portability Analyzer

In line with the Microsoft documentation, the first step to migrating to .NET 5 is to assess the extent of the work that needs to be done on the existing application so that you can determine the extent of the tasks you need to complete to make the application compliant with .NET 5 before migrating to it. 

Important: 

Sometimes there is a path forward for code. This code uses APIs that are no longer supported. All other changes require additional effort and a new approach. Visual Studio extension makes it possible to access the .NET Portability Analyzer.

Step 2: Inspect Project Dependencies 

Assess dependencies between projects and decide whether to upgrade library classes to .NET Standard or .NET 5.  You should keep in mind that if all projects are being upgraded to .NET 5, then all projects can target .NET 5 at the same time.

As a general rule of thumb, whenever you need to leave a project in .NET Framework and that project needs to reference an upgraded class project, then you should target .NET Standard 2.0 instead of .NET 5. In this particular case, you have to adhere to the CMSApp project that represents the Kentico Admin tool. 

Think of the CMSApp project that represents the Kentico Admin tool (it is in .NET framework 4.x and you will most likely need to share code between those projects for things like custom external media storage modules).

If you are not sure, you can also lookup the .NET Standard implementation support page to determine what versions of .NET and .NET Standard are compatible with each other.

Important: Check your .NET and .NET Standard versions to make sure they are compatible. You can check the compatibility by visiting the .NET Standard implementation support page. This page can be used as a reference one. 

Step 3: Convert Class Libraries

In order to make the conversion process as simple as possible, We recommend converting your class libraries (your helpers, extensions, custom scheduled tasks, reusable components, etc.) because they are the easiest to convert. There is no guarantee that all of the existing code will be able to be converted into the new project structure without any problems as long as there are no compatibility warnings in Step 1. 

In order to begin the conversion process, you must make sure that the version of the .NET SDK that you wish to use is installed on your local machine before you start converting your projects.

When you are ready to migrate your projects, you can start with the Try Convert tool. This tool is used if you want to check whether you will be able to migrate your entire solution or single projects automatically after implementing the tool. If you want to do manual conversion, take the following steps:

1. Create a new Class Library project in 3 ways: 1) either the same folder with a new project name;  2) in a parallel folder with the same project name using either Visual Studio (Add > New Project > Class Library), 3). Or with the CLI command dotnet new classlib -o <ProjectName>

2. It is recommended to replace the old project name csproj file with the new one that has just been created if using the same project name.

3. In order to ensure that your code is working correctly, you need to manage Nuget packages for your new project and add any missing packages. The packages.config file can also be migrated to the PackageReference file by right-clicking the file in Visual Studio and selecting the "Migrate packages.config to PackageReference" option.

4. As Nuget packages are now managed in the csproj file, you can delete the Properties folder and packages.config file.

5. Ensure that the project is built and that any missing references or errors are fixed.

Step 4: Convert ASP.NET Projects (The Hardest Part)

The way .NET Core and .NET 5 initialize and run ASP.NET MVC projects has changed significantly, so migrating class libraries tends to be less involved. In the same way like in Step 3, Try Convert. 

For manual conversion, try to take the following steps: 

1.Create a new Class Library project in either the same folder or in a parallel folder. For that purpose you can use Visual Studio (Add > New Project > Class Library), or with the CLI command dotnet new classlib -o <ProjectName>.

2. Normally, the class file for the csproj will be replaced with the new, created file of the csproj in cases where the project name remains the same.

3. Keeping the Nuget packages for your new project up-to-date will ensure that the code in your new project is working as intended. You will need to add any missing packages as soon as possible.

Whenever you right click on the packages.config file in Visual Studio, you have the option of selecting 'Migrate packages.config to PackageReference'.

4. Make sure to delete all the unnecessary files and folders like the Properties folder and packages.config file, which might not be needed anymore.

5. Make sure all references and errors are fixed before building the project

Step 5: Review Dependency Injection

Using Dependency Injection with your existing framework is likely to be a good choice.

You can use the built-in Dependency Injection framework even if you have not used DI at all before migrating to .NET 5.

Despite the fact that you might be using a different DI framework, you may want to consider switching to .NET Dependency Injection because of its excellent performance, and because it is a first-class citizen of .NET, it will be very easy to adopt and implement.

In my opinion, .NET Core comes with an excellent built-in DI framework which I find very useful.

Step 6: Migrate to System.Text.Json (optional)

System.Text.Json is an optional migration option for serialization and deserialization. There is no feature parity between Newtonsoft.Json and System if you are currently using Newtonsoft.Json.

If you switch to System.Text.Json, you will most likely notice an improvement in performance as well, since System.Text.Json has all the features you need for your application. 

Important! As a result of making the switch, you will most likely see improvements in your performance as a result. I would also like to point out that you should not perform this step on the Kentico CMSApp project. There is still a requirement for Newtonsoft there. Migrating to System.Text.Json is typically accomplished in the following manner:

1. Your project(s) should no longer contain references to Newtonsoft.Json.

2. It should be possible for you to get build errors for everything that was using Newtonsoft when you build your solution.

3. Change Newtonsoft.Json to System.Text.Json, typically by removing Newtonsoft.Json and replacing it with System.Text.Json.

4. Introducing updated serialization and deserialization syntax: SerializeObject() will be replaced by JsonSerializer.Serialize() and DeserializeObject() will be replaced by JsonSerializer.Deserialize().

Step 7: Migrate Forms to the new Form Builder (optional)

Depending on your situation, you may not need to do this step. The way Kentico Xperience 13 handles forms will need to be changed if your old forms were built in Kentico 12. Form builder development documentation is a good place to start. Upgrades from 12 to 13 may have caused issues around this area. For the upgrade to work, we actually had to delete the forms from the system in order to make the upgrade work. Generally speaking, you will have to rebuild your forms in 13 as a result of the changes to the XML format. While there are some crazy workarounds that can be done, it would require a whole new blog post to tell the story of those workarounds. It is possible to ignore this step if you are building your forms in Xperience 13 using the Form builder from the beginning.

Step 8: Treat it like an Upgrade (optional) 

You may wish to perform an optional step as well. But from a Kentico standpoint, it is highly likely that you will want to review, rebuild, retest anything and everything that is currently on the MVC live website. 

When adding new images to the Kentico media library, make sure that they are being delivered correctly and increase the frequency with which you check your event log for errors. Rebuild your search indexes, clean / restart your web farm servers, and make sure that the files are being delivered correctly. 

Summary

Switching from .NET Framework 4.x to the latest .NET platform might seem challenging to some, but the benefits are far greater than the challenges. Besides the immediate performance improvements, you will be able to take advantage of the latest .NET platform, which will continue to improve over time.

All you need to do is to  invest your time, resources, and effort into upgrading Kentico Portal Engine to a high level, especially if the portal engine must be converted to Kentico MVC. The release of .NET Core / .NET 5 / .NET 6 was over 5 years ago in 2021. 

Below I have compiled a whole list of benefits associated with the importance of .NET:

1.     relatively easy Deployment 

2.    Use for Service-Oriented Architecture (SOA) 

3.    Free, Open-Source Platform

4.    Requires less coding  

5.     Advanced UI Controls 

6.     Safety and Security

7.     Use Across Platforms and Languages 

8.     Memory Management  

9.    Interoperability

                                                             References: 

What's new in .NET 5. Microsoft docs.