Introduction
In this article, I walk you through updating an existing .NET Core 2. x Web API application to .NET Core 3.1. Migrating to .NET core 3.1 will help you take the advantage of .NET core 3.1.
Here you will find the new features of .NET core 3.1.
I will explain all the steps I did to migrate one of my projects. There were a lot of breaking changes in the newer version. You can find all the breaking changes here.
Prerequisites
Visual Studio 2019 (As .NET core 3. x works on VS 2019)
Update Target Framework from .net core 2. x to 3.1
Go to your project properties and change the Target Framework
Or you can search for tag <TargetFramework> in the .csproj file and change its value to "netcoreapp3.1" as shown below.
Delete the NuGet Package References that Have Been Removed and Moved to the Shared Library
Remove "Microsoft.AspNetCore.App" from your project Dependencies or .csproj file.
Remove "Microsoft.AspNetCore.App.Razor.Design" from your project Dependencies or .csproj file.
Update NuGet package references (If applicable, Either in .csproj file or directly in your project Dependencies)
Swagger
It is used for API Documentation. If you are using then update to version “Swashbuckle.AspNetCore” to version 5.5.1There are many changes in Swagger configuration in .NET core 3.1
NewtonSoft/ Any JSON Serializer
If you are using any JSON serializer, then add the reference of “Microsoft.AspNetCore.Mvc.NewtonsoftJson” of version 3.1.5 Because in .NET core 3.1, Microsoft has introduced an in-build faster JSON serializer.&
KestrelWeb Server
Kestrel is a preferred web server that is implemented on basis of Libuv library (Which is also used in node.js), If you are using it in your application, Then update “Microsoft.ServiceFabric.AspNetCore.Kestrel” to version 4.1.417
Note. If you are using Nagle algorithm (NoDelay) in Kestrel webserver to reduce the number of packets over the TCP network to improve the efficiency, like below (in your kestrel configuration).
Then, you need to add following Nuget package as it is moved to separate package
“Microsoft.AspNetCore.Server.Kestrel.Transport.Libuv” of version 3.1.5
Modify ConfigureServices method of Startup.cs
Replace AddMvc with AddControllers, Microsoft replaced AddMVC with two options.
- Web Application (MVC) - We should replace AddMVC with AddControllersWithViews
- Web API - We should replace AddMVC with AddControllers, The motivation here is to not load the libraries or components which are related to views
From
To
Replace the .Net Core MVC Compatability version from 2.xto 3.0 in SetCompatibilityVersion
From
To
Replace AddJsonOptions with AddNewtonsoftJson It is inbuilt faster JSON Serializer as covered in #3.b
From
To
If you allow HTTP requests from cross origin or cross domains, then replace WithOrigins("*")with AllowAnyOrigin()
From
To
If you are using Swagger for API documentation, then change the below bold text:
From
To
I will cover SwaggerParametersFilter in #6.
In Configure Method of Startup.cs
Replace, IHostingEnvironment with IWebHostEnvironment HostingEnviorment is obsolete now and it will be removed from future version of .net core. It is injected in controller and gives the information of applications web hosting enviornment.
From
To
Use your CORS Policy name define in #4.d, instead of defining rules here.
From
To
Here CorsPolicy is the name of Cors policy.
Replace app.UseMvc() with EndPoint Routing, as below.
From
To
In .NET core, The EndPoint routing is the new feature introduced, It provides the routing information in the middleware of your request pipeline.
So, the difference between AddMVC and EndPoint routing is that the AddMVC provides the routing information after the completion of middleware of your request pipeline, So we did not have route information in middleware. In the Endpoint routing, we are configuring it and getting it inside the middleware request pipeline.
If you are using Swagger Operation Filter to apply some logic globally on your all actions method or endpoints, then change the bold text below.
From
To
If you are usingStatelessService with Kestrel, Then in theCreateServiceInstanceListenersmethod, if you are usinglistenOptions.NoDelay =true; (It is using Nagle which was covered in #3.c section for efficiency)
From
To (Remove the bold blue text and add configuration of "UseLibuv" as below)
If you are using Service Fabric to host your API / Microservice, then please update the Service Fabric cluster with the latest version.
Conclusion
I tried to cover almost all the basic things that people generally use in API implementation. The good thing is that .NET Core 3.1 has long-term support (until December 3, 2022).
Thanks for reading this article!