Welcome to today’s post.
Today I will be showing how we can migrate from an existing ASP.NET Core 2.0 Web API application to a ASP.NET Core 3.1 Web API application.
I Will be covering this migration in three parts:
Part 1 – Common packages
- Migrating of ASP.NET Core packages.
- Updating Entity Framework Core packages.
- Updating JSON Token security packages.
- Updating Entity Framework Core for SQL Server.
- Update to MVC Endpoint Routing.
- Endpoint Routing for Controllers with Attribute Routing.
- Update to JSON Formatting
- Discussion of the HTTP 500 error.
Part 2 – Swagger and OData packages
- Updating OData packages.
- Updating Swagger (Open API) packages.
Part 3 – Identity Server and Entity Framework Core SQL Extensions
- Updating ASP.NET Core Identity packages.
- Entity Framework Core SQL Server extensions.
- Additional notes on Swagger (Open API) types.
The first part I will cover in this post, and the remaining two parts will be covered in the next two posts.
Another more obvious upgrade route might be to create a fresh ASP.NET Core 3.1 Web API from the Visual Studio 2019 Web Application template and then port our code from our original ASP.NET Core 2.0/2.1 version across into the new ASP.NET Core 3.1 API application.
I will go with the strategy of migrating the existing application code base and show with each step along the way how to achieve our goal.
Migrating ASP.NET Core Library Packages
First, we open an existing .NET Core 2.0 Web API using Visual Studio 2019. A legacy .NET Core (pre .NET Core 3.1) application should be able to run in Visual Studio 2019, however all of .NET Core prior to version 3.0 is no longer being supported by Microsoft. After the application has loaded, open the project properties. You will see a screen similar to that below:
Next, change the Target Framework to version 3.1 as shown:
Next save changes.
Now comes the fun. Try rebuilding the solution.
You will see some errors in the build console window.
Rather than present you with a dictionary full of all possible errors and how to fix them, I will go other some of the most common and how to tackle them during the porting and upgrade process.
The first error we get is a package error as shown:
The Microsoft.AspNetCore.All package is not supported when targeting .NET Core 3.0 or higher. A FrameworkReference to Microsoft.AspNetCore.App should be used instead, and will be implicitly included by Microsoft.NET.Sdk.Web.
In our CSPROJ file, we remove the reference to Microsoft.AspNetCore.All and rebuild:
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.9" />
<PackageReference Include="Microsoft.AspNetCore.OData" Version="7.2.3" />
<PackageReference Include="Microsoft.Azure.ServiceBus" Version="4.1.2" />
<PackageReference Include="Microsoft.VisualStudio.Azure.Containers.Tools.Targets" Version="1.4.10" />
<PackageReference Include="Swashbuckle.AspNetCore.Swagger" Version="4.0.1" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerGen" Version="4.0.1" />
<PackageReference Include="Swashbuckle.AspNetCore.SwaggerUi" Version="4.0.1" />
</ItemGroup>
The next section is useful if you have projects that use the Entity Framework Core library for data access. If not applicable, you may wish to skip to the subsequent section.
Entity Framework Core Errors
Below are some common errors we get from using Entity Framework Core:
error CS0234: The type or namespace name 'EntityFrameworkCore' does not exist in the namespace 'Microsoft' (are you missing an assembly reference?)
error CS0246: The type or namespace name 'DbContext' could not be found (are you missing a using directive or an assembly reference?)
error CS0246: The type or namespace name 'ModelBuilder' could not be found (are you missing a using directive or an assembly reference?)
error CS0246: The type or namespace name 'DbSet<>' could not be found (are you missing a using directive or an assembly reference?)
error CS0246: The type or namespace name 'DbContextOptions<>' could not be found (are you missing a using directive or an assembly reference?)
Recommended update: The version of EF Core NuGet package Microsoft.EntityFrameworkCore we use for .NET Core 2.0 is 2.0.0. To upgrade to the next version of EF Core will require us moving to package version 3.1.0. After the update, there is no need to change any import (using) statements or references to classes within EF Core. It should work normally.
JSON Bearer Token Security Errors
Below are some common errors we get from using JSON Bearer Token Security libraries:
error CS0234: The type or namespace name 'JwtBearer' does not exist in the namespace 'Microsoft.AspNetCore.Authentication' (are you missing an assembly reference?)
error CS0103: The name 'JwtBearerDefaults' does not exist in the current context
Recommended update: Add the NuGet package Microsoft.AspNetCore.Authentication.JwtBearer with version 3.1.0. Following the update there is no need to change any imports. Just continue using the following imports within your code:
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
SQL Server Support for Entity Framework Core
Below is a common error we get from using SQL Server within our application data contexts:
CS1061 'DbContextOptionsBuilder' does not contain a definition for 'UseSqlServer'
and no accessible extension method 'UseSqlServer' accepting a first argument of type
'DbContextOptionsBuilder' could be found
(are you missing a using directive or an assembly reference?)
Recommended update: Add the NuGet packages:
Microsoft.EntityFrameworkCore.SqlServer version 3.1
Microsoft.EntityFrameworkCore.Relational version 3.1
Following the update there is no need to update import statements.
Changes to the Web Host Start Up
Below is a warning we get from within Startup.cs:
warning CS0618: 'IHostingEnvironment' is obsolete: 'This type is obsolete and will be removed in a future version. The recommended alternative is Microsoft.AspNetCore.Hosting.IWebHostEnvironment.'
An example of this issue is shown in the code segment below:
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
...
Note: As of .Net Core 3.1, IHostingEnvironment will be deprecated and replaced with IHostEnvironment. To rectify we apply the following namespace import and change to the code :
using Microsoft.Extensions.Hosting;
public void Configure(IApplicationBuilder app, IHostEnvironment env)
{
Endpoint Routing and MVC
The ASP.NET Core 3.1 libraries do not support MVC with Endpoint routing.
If you attempt to use MVC and endpoint routing you will get the following warning:
Warning MVC1005: Using ‘UseMvc’ to configure MVC is not supported while using Endpoint Routing. To continue using ‘UseMvc’, please set ‘MvcOptions.EnableEndpointRouting = false’ inside ‘ConfigureServices’.
For example, the following code segment will not work with endpoint routing enabled:
public void Configure(IApplicationBuilder app, IHostEnvironment env)
{
app.UseMvc(o =>
{
…
});
…
Recommended update: To fix this situation, make the following change to move the MVC routing within ConfigureServices:
public void ConfigureServices(IServiceCollection services)
{
…
services.AddMvc(opt =>
{
opt.EnableEndpointRouting = false;
});
Endpoint Routing for Controllers with Attribute Routing
If endpoints are not mapped to controllers that have attribute routing, the following error will occur:
Not found 404 error
Recommended update: Use the MapControllers() extension method to map attribute routed controllers:
app.UseEndpoints(endpoints =>
{
endpoints.MapControllers();
});
Newtonsoft JSON Library Update
The ASP.NET Core 3.1 update requires libraries that use JSON formatting to be upgraded as well.
With MVC model binding for input and output formatting for JSON and JSON PATCH will change. The error you will get is shown below:
CS1503 Argument 2:
cannot convert from 'Microsoft.AspNetCore.Mvc.ModelBinding.ModelStateDictionary' to
'System.Action<Microsoft.AspNetCore.JsonPatch.JsonPatchError>'
Recommended update: To resolve this issue install the Nuget package Microsoft.AspNetCore.Mvc.NewtonsoftJson version 3.1.0. The package includes ASP.NET Core MVC features that use Newtonsoft.Json and includes input and output formatters for JSON and JSON PATCH. This will also uninstall NuGet package Microsoft.AspNetCore.JsonPatch version 2.0.0. and replace it with version 3.1.0. NuGet package Newtonsoft.Json version 10.0.3 will be replaced with version 10.0.2.
Runtime Error HTTP ERROR 500.37 ANCM
This error is quite common after an upgrade from a previous version of .NET Core. The error most frequently occurs when a call within Startup.cs times out. Situations where this can occur include:
- An invalid connection string within the appSettings.json that is read by the EF Core data context and exceeds the maximum timeout.
- An invalid service collection binding that causes the subsequent code to not run.
If your application is slow to startup then I recommend setting the timeout in web.config.
Following the installation of the mentioned NuGet packages, your solution package list would look like the list below:
That’s all for today’s post.
In the next post I will be discussing how to upgrade ASP.NET Core Web API applications that use OData and Swagger UI.
I hope you found this post useful and informative.
Andrew Halil is a blogger, author and software developer with expertise of many areas in the information technology industry including full-stack web and native cloud based development, test driven development and Devops.
