daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/migration/20_21.md

11 KiB
Raw Blame History

title author description ms.author ms.date uid
Migrate from ASP.NET Core 2.0 to 2.1 rick-anderson This article covers the basics of migrating an ASP.NET Core 2.0 app to 2.1. riande 05/30/2018 migration/20_21

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:

[!code-xmlMain]

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

[!code-xmlMain]

Rules for projects targeting the shared runtime

ASP.NET Core includes the following shared runtimes:

Rules for projects targeting the shared runtime:

  • Projects referencing the Microsoft.AspNetCore.All or Microsoft.AspNetCore.App packages must set the project's SDK to Microsoft.NET.Sdk.Web at the top of the project file (<Project Sdk="Microsoft.NET.Sdk.Web">).
  • Projects referencing packages or projects that transitively reference Microsoft.AspNetCore.All or Microsoft.AspNetCore.App:
    • Must set the project's SDK to Microsoft.NET.Sdk.Web at the top of the project file (<Project Sdk="Microsoft.NET.Sdk.Web">).
    • Must reference the same shared runtime package. If LibraryA references Microsoft.AspNetCore.App, any projects referencing LibraryA must also reference Microsoft.AspNetCore.App.
  • Executable projects (projects that contain apps that are launched with dotnet run or apps that run and test projects for apps) must not specify a version for Microsoft.AspNetCore.App. The SDK specifies the version implicitly via <PackageReference Include="Microsoft.AspNetCore.App" />.
  • Referenced projects (projects that aren't the entry point and the project references Microsoft.AspNetCore.All or Microsoft.AspNetCore.App) must specify a package version.

Changes to take advantage of the new code-based idioms that are recommended in ASP.NET Core 2.1

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:

[!code-csharpMain]

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:

[!code-csharpMain]

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 (RCL).

The default 2.1 Identity UI doesn't currently provide significant new features over the 2.0 version. Replacing Identity with the RCL package is optional. The advantages to replacing the template generated Identity code with the RCL version include:

  • Many files are moved out of your source tree.
  • Any bug fixes or new features to Identity are included in the Microsoft.AspNetCore.App metapackage. You automatically get the updated Identity when Microsoft.AspNetCore.App is updated.

If you've made non-trivial changes to the template generated Identity code:

  • The preceding advantages may not justify converting to the the RCL version.
  • You can keep your ASP.NET Core 2.0 Identity code, it's fully supported.

Identity 2.1 exposes endpoints with the Identity area. For example, the follow table shows examples of Identity endpoints that change from 2.0 to 2.1:

2.0 URL 2.1 URL
/Account/Login /Identity/Account/Login
/Account/Logout /Identity/Account/Logout
/Account/Manage /Identity/Account/Manage

Applications that have code using Identity and replace 2.0 Identity UI with the 2.1 Identity Library need to take into account Identity URLs have /Identity segement prepended to the URIs. One way to handle the new Identity endpoints is to set up redirects, for example from /Account/Login to /Identity/Account/Login.

Update Identity to version 2.1

The following options are available to update Identity to 2.1.

  • Use the Identity UI 2.0 code with no changes. Using Identity UI 2.0 code is fully supported. This is a good approach when signficant changes have been made to the generated Identity code.
  • Delete your existing Identity 2.0 code and Scaffold Identity into your project. Your project will use the ASP.NET Core Identity Razor Class Library. You can generate code and UI for any of the Identity UI code that you modified. Apply your code changes to the newly scaffolded UI code.
  • Delete your existing Identity 2.0 code and Scaffold Identity into your project with the option to Override all files.

Replace Identity 2.0 UI with the Identity 2.1 Razor Class Library

This section outlines the steps to replace the ASP.NET Core 2.0 template generated Identity code with the ASP.NET Core Identity Razor Class Library. The following steps are for a Razor Pages project, but the approach for an MVC project is similar.

  • Verify the project file is updated to use 2.1 versions
  • Delete the following folders and all the files in them:
    • Controllers
    • Pages/Account/
    • Extensions
  • Build the project.
  • Scaffold Identity into your project:
    • Select the projects exiting _Layout.cshtml file.
    • Select the + icon on the right side of the Data context class. Accept the default name.
    • Select Add to create a new Data context class. Creating a new data context is required for to scaffold. You remove the new data context in the next section.

Update after scaffolding Identity

  • Delete the Identity scaffolder generated IdentityDbContext derrived class in the Areas/Identity/Data/ folder.

  • Delete Areas/Identity/IdentityHostingStartup.cs

  • Update the _LoginPartial.cshtml file:

    • Move Pages/_LoginPartial.cshtml to Pages/Shared/_LoginPartial.cshtml
    • Add asp-area="Identity" to the form and achor links.
    • Update the <form /> element to <form asp-area="Identity" asp-page="/Account/Logout" asp-route-returnUrl="@Url.Page("/Index", new { area = "" })" method="post" id="logoutForm" class="navbar-right">

    The following code shows the updated _LoginPartial.cshtml file:

    [!code-cshtmlMain]

Update ConfigureServices with the following code:

[!code-csharpMain]

Changes to Razor Pages projects Razor files

The layout file

  • Move Pages/_Layout.cshtml 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