Migrate from ASP.NET Core 2.0 to 2.1

By Rick Anderson

See What's new in ASP.NET Core 2.1 for an overview of the new features in ASP.NET Core 2.1.

This article:

  • Covers the basics of migrating an ASP.NET Core 2.0 app to 2.1.
  • Provides an overview of the changes to the ASP.NET Core web application templates.

A quick way to get an overview of the changes in 2.1 is to:

  • Create an ASP.NET Core 2.0 web app named WebApp1.
  • Commit the WebApp1 in a source control system.
  • Delete WebApp1 and create an ASP.NET Core 2.1 web app named WebApp1 in the same place.
  • Review the changes in the 2.1 version.

This article provides an overview on migration to ASP.NET Core 2.1. It does not contain a complete list of all changes needed to migrate to version 2.1. Some projects might require more steps depending on the options selected when the project was created and modifications made to the project.

Update the project file to use 2.1 versions

Update the .csproj project file:

  • Change <TargetFramework>netcoreapp2.0</TargetFramework> to the 2.1 version, that is <TargetFramework>netcoreapp2.1</TargetFramework>.

  • Replace the version specified "Microsoft.AspNetCore.All" package reference with the versionless "Microsoft.AspNetCore.App" package reference. You may need to add dependencies that were removed from "Microsoft.AspNetCore.All". See Migrating from Microsoft.AspNetCore.All to Microsoft.AspNetCore.App and Microsoft.AspNetCore.App metapackage. If you're targetting the .NET Framework:

    • Add individual package references instead of a meta package reference.
    • Update each package reference to 2.1.
  • Remove all references to <DotNetCliToolReference> elements for "Microsoft.AspNetCore", "Microsoft.VisualStudio", and "Microsoft.EntityFrameworkCore" packages. These tools have been replaced by global tools.

The following markup shows the template generated 2.0 .csproj project file:

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.0</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.All" Version="2.0.8" />
    <PackageReference Include="Microsoft.EntityFrameworkCore.Tools" Version="2.0.3" PrivateAssets="All" />
    <PackageReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Design" Version="2.0.4" PrivateAssets="All" />
  </ItemGroup>
  <ItemGroup>
    <DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.3" />
    <DotNetCliToolReference Include="Microsoft.Extensions.SecretManager.Tools" Version="2.0.2" />
    <DotNetCliToolReference Include="Microsoft.VisualStudio.Web.CodeGeneration.Tools" Version="2.0.4" />
  </ItemGroup>
</Project>

The following markup shows the template generated 2.1 .csproj project file:

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

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <UserSecretsId>aspnet-{Project Name}-{GUID}</UserSecretsId>
  </PropertyGroup>

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

</Project>

Rules for projects targeting the shared runtime

ASP.NET Core includes the following shared runtimes:

Rules for projects targeting the shared runtime:

  • Projects referencing Microsoft.AspNetCore.All or Microsoft.AspNetCore.App packages, must reference Microsoft.Net.Sdk.Web Sdk.
  • Projects referencing packages or projects that transitively reference Microsoft.AspNetCore.All or Microsoft.AspNetCore.App:
    • Must reference the Microsoft.Net.Sdk.Web Sdk and,
    • Must reference the same shared runtime package. For example, if LibraryA references Microsoft.AspNetCore.App, any projects referencing it must reference Microsoft.AspNetCore.App.
  • Executable projects:
    • Are projects that contain apps that are launched with dotnet run.
    • Are applications that run and test projects for applications.
    • Executable projects must not specify the version. The Sdk specifies the version implicitly via <PackageReference Include="Microsoft.AspNetCore.App" />.
  • Referenced projects, that is:
    • Projects that aren’t the entry point, and
    • The project references Microsoft.AspNetCore.All or Microsoft.AspNetCore.App.
    • Referenced projects must specify a package version.

Changes to Main

The following images show the changes made to the templated generated Program.cs file.

old version differences

The preceding image shows the 2.0 version with the deletions in red.

The following image shows the 2.1 code. The code in green replaced the 2.0 version:

new version differences

The following code shows the 2.1 version of Program.cs:

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

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

The new Main replaces the call to BuildWebHost with CreateWebHostBuilder. IWebHostBuilder was added to support a new integration test infrastructure.

Changes to Startup

The following code shows the changes to 2.1 template generated code. All changes are newly added code, except that UseBrowserLink has been removed:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace WebApp1
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.Configure<CookiePolicyOptions>(options =>
            {
                // This lambda determines whether user consent for non-essential cookies is needed for a given request.
                options.CheckConsentNeeded = context => true;
                options.MinimumSameSitePolicy = SameSiteMode.None;
            });


            services.AddMvc()
                .SetCompatibilityVersion(CompatibilityVersion.Version_2_1);
        }

        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                app.UseExceptionHandler("/Error");
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseStaticFiles();
            app.UseCookiePolicy();

            app.UseMvc();
        }
    }
}

The preceding code changes are detailed in:

Changes to authentication code

ASP.NET Core 2.1 provides ASP.NET Core Identity as a Razor Class Library. If you have not made substantial changes to the 2.0 template generated Identity code, consider the following upgrade approach:

Changes to Razor Pages projects Razor files

The layout file

  • Pages/_Layout.cshtml moves to Pages/Shared/_Layout.cshtml

  • The Layout.cshtml file has the following changes:

    • <partial name="_CookieConsentPartial" /> is added. For more information, see GDPR support in ASP.NET Core.
    • jQuery changes from 2.2.0 to 3.3.1

_ValidationScriptsPartial.cshtml

  • Pages/_ValidationScriptsPartial.cshtml moves to Pages/Shared/_ValidationScriptsPartial.cshtml
  • jquery.validate/1.14.0 changes to jquery.validate/1.17.0

New files

The following files are added:

  • Privacy.cshtml
  • Privacy.cshtml.cs

See GDPR support in ASP.NET Core for information on the preceding files.

Changes to MVC projects Razor files

The layout file

The Layout.cshtml file has the following changes:

  • <partial name="_CookieConsentPartial" /> is added.
  • jQuery changes from 2.2.0 to 3.3.1

_ValidationScriptsPartial.cshtml

jquery.validate/1.14.0 changes to jquery.validate/1.17.0

New files and action methods

The following are added:

  • Views/Home/Privacy.cshtml
  • The Privacy action method is added to the Home controller.

See GDPR support in ASP.NET Core for information on the preceding files.

Additional changes