Migration from ASP.NET Core 2.0 to 2.1

On May 30th .NET Core 2.1 was released including the corresponding version of ASP.NET Core 2.1 and Entity Framework Core 2.1. In this post, I will be taking one of the projects used in my ASP.NET Basics series and converting it from its current 2.0.x version into the newly released 2.1 version. The starting point for the code can be found here. This is all based on the official migration guide.

If you are looking at the sample solution it is the Contacts project that this post is going to be dealing with.

Installation

Thankfully the download page is much improved over the last time there was a release. Head here and to download and install the .NET Core 2.1 SDK. It is available for Windows, Linux, and Mac. The link should drop you on the appropriate page for your OS.

After installation, open a command prompt and run the following command. If all worked well you should see version 2.1.300 listed.

dotnet --list-sdks

If you are on Windows make sure and install at least Visual Studio 2017 15.7.

Project File Changes

Right-click on the project and select Edit {projectName}.csproj from the menu.

First, change the TargetFramework to netcoreappp2.1.

Before:
<TargetFramework>netcoreapp2.0</TargetFramework>

After:
<TargetFramework>netcoreapp2.1</TargetFramework>

The other required changes it to move away from the Microsoft.AspNetCore.All package to the version-less Microsoft.AspNetCore.App package.

Before:
<PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.0" />

After:
<PackageReference Include="Microsoft.AspNetCore.App" />

I did a bit more digging and it turns out that the project file can be greatly simplified from the version I had for this application. The following is the full project file will all the bits that were not required removed and the two changes above already made.

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <UserSecretsId>Your-Secrests-ID</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.1.0" PrivateAssets="All" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="1.0.0" />
  </ItemGroup>

</Project>

Main Changes

There have been changes to how what the Main function looks like to better allow for integration tests. This is the original code in the Program.cs file.

public class Program
{
    public static void Main(string[] args)
    {
        BuildWebHost(args).Run();
    }

    public static IWebHost BuildWebHost(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>()
            .Build();
}

And the following is the new version.

public class Program
{
    public static void Main(string[] args)
    {
        CreateWebHostBuilder(args).Build().Run();
    }

    public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
        WebHost.CreateDefaultBuilder(args)
            .UseStartup<Startup>();
}

Startup Changes

Startup.cs has one change that is required which is the removal of the following line from the Configure function.

app.UseBrowserLink();

In the ConfigureServices function if you want to use the new features in 2.1 change the services.AddMvc() to set the compatibility version. This allows you to upgrade the version of the SDK without having to change your whole application since you have to opt into the version you want to target.

Before:
services.AddMvc();

After:
services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

If you check out the official migration guide they also point out how to enable a couple more features such as HTTPS and some things to help with GDPR. Neither of these is needed in this application so I’m skipping them in this guide.

Identity Changes

I had to make one change in ManageLogins.cshtml to get my project to build because of a rename/removal AuthenticationScheme to DisplayName.

Before:
<button type="submit" class="btn btn-default" name="provider" value="@provider.AuthenticationScheme" title="Log in using your @provider.DisplayName account">@provider.AuthenticationScheme</button>

After:
<button type="submit" class="btn btn-default" name="provider" value="@provider.DisplayName" title="Log in using your @provider.DisplayName account">@provider.DisplayName</button>

If you haven’t made many changes to the identity code in your project you might consider using the new identity razor class library. You can find the details here.

Wrapping Up

Migrations between versions of ASP.NET Core have gotten easier over time as you can tell by the smaller length of these posts. One thing to note is while this will get you targeting 2.1 with all the performance benefits and access to a lot of the new features there will still be work needed if you want to do everything the new 2.1 style. I highly recommend creating a new 2.1 application to get a feel for the other changes you might want to make to your existing applications.

The code with all the changes can be found here. Remember that the only project that was upgraded was the Contacts project.

---

Also published on Medium.