Migration from Asp.Net Core 2.2 to 3.1 — Real project

Alexandre Malavasi
6 min readDec 15, 2019

The purpose of this article is to share my personal experience of migrating a medium complexity real project from Asp.Net Core 2.2 and Asp.Net 3.1.

The project uses the following stack:

  • Asp.Net Core Web API
  • Vue JS front-end without any Razor Pages used in the project. The entire front-end is a Vue JS application
  • Entity Framework Core (Code First approach)
  • SQL Server Database

At the beginning of my career, almost all the time I decided to postpone the upgrade of .NET projects under my responsibility to the newest version of the underlying technology. There are many factors that should be considered before migrating a system: costs, effort, complexity, business value, etc. Therefore, depends on the scenario, many projects aren’t migrated to a newer version.

I changed my mind in the last years, manly after the launch of the first version of .NET Core. The first migrations from .NET Framework to .NET Core might be problematic for complex projects, but the migrations between .NET Core version, usually, are not that hard.

In the rest of the article, I’m going to demonstrate all the steps I made to migrate a real project, all the problems and, of course, the solutions I’ve found and applied.

Framework version change

After that, I ran the project just to see the number of errors the Solution would have after this change. And that is the result:

That is saying it got more than 900 errors! The project is not so big and a good amount of the problems are related to the Nuget packages version.

But, my biggest curiosity was the Entity Framework incompatibility issues. So, let's see what I found.

Entity Framework Core

The first thing I did was update all the packages associated with EF Core to avoid the need for too many useless incompatibility issues. I upgraded the packages to the 3.1 version.

Once that was done, I got a problem with the SQL Server library to Entity Framework. The issue was solved by installing the package for SQL Server in separate (Microsoft.EntityFramework.SqlServer):

I built the project again and it sill getting many errors, as follows:

PS: Many of them can be solved just by cleaning the Solution and building it again. I updated again all the packages to the newest version, in case of it exists.

Project file (.csproj)

The next step was to verify the compile errors and warnings reference to project file configuration (.csproj). In my case, after analyzing the compile error messages, I removed the following lines from the file:

According to the official documentation, these entries are useless in .NET Core 3.1.

Nuget package updates

Logically, the next step was to upgrade the rest of the packages used by the application to the newest possible version. In that context, I was using just third party libraries for Vue JS Middleware and native libraries of .NET Core. But, it might be different in your scenario. So, it is really important to analyze it before your own migration.


The most relevant changes were on the Startup file, because of since version 3.0 of Asp.Net Core, the route configuration changed completely. Now there are more options for specific situations. For instance, you don’t need anymore configure an application to use the entire MVC engine if your application is just a Web API and, therefore, does not use View or Razor Pages. You can add configuration just for Controllers in that case. It is much better I think.

So, the first thing I did in the file was removing the references to Microsoft.AspNetCore.Mvc to use Microsoft.Extensions.Hosting:

Also, instead of use “AddMvc” to set the route configuration, I used “UseEndPoints”, which one is available since the first version of .NET Core 3.0. Using that, I mapped the Controllers, because the backend of my project is a Web API:

The interface IHostEnvironment was replaced by IWebHostEnvironment, as follows:

Extra problems

After finally being able to run the project without errors in compile-time, I quickly get an error in runtime, when it tried to initialize:

I searched in some Github forums and figured out the error was caused by the non-installation of this package:

As I was using a Middleware for Vue JS and running the application as SPA (Single Page Application), the installation of this package was missing. If you use the middleware for Angular or React, possibly you’ll get the same error and that is the solution.

Finally, I was able to run the project, without any extra issues and it worked perfectly.


In my opinion, it is much better to migrate to the 3.1 .NET Core version if the application is already in 2.x version. It is quite stable at this point and one day you’ll have to migrate to it, so why not? I believe it does not contain many break changes. But, surely, I would say that It is always better to check it in your own scenario, that might be different from mine.

I hope this article has helped and encouraged you in case you are thinking to migrate your project to .NET Core 3.1.

In case of any questions, please feel free to leave it here or in any of my social profiles.

Thank you for reading this article till the end. The following are my social media profiles where I frequently share my technical posts and information on IT Events.

Twitter: https://twitter.com/alemalavasi
Linkedin: https://www.linkedin.com/in/alexandremalavasi/

My Book

I’m glad to announce that I have my first book published. It is a deep dive hands-on through the most common Design Patterns used in .NET applications. The book contains hundreds of code samples and explanations based on real-world scenarios. It also has many examples of Object-Oriented Programming, SOLID principles, and all the path to get yourself familiar with .NET 5 and C#. Check it out:



Alexandre Malavasi

Microsoft MVP | MCP | MCTS | MCPD | ITIL | .NET | MBA | MTAC | Technical Leader | Consultant | .NET Developer