From 5cdd18fc8390b6caceee29761fb1646313a40366 Mon Sep 17 00:00:00 2001 From: Nate McMaster Date: Tue, 10 Jul 2018 13:01:56 -0700 Subject: [PATCH] Update the migration docs to remove instructions for versionless package references (#7543) Follow up to https://github.com/aspnet/Docs/pull/7540 I found one more reference to versionless packages. I've updated the migration guide to remove this recommendation, and also briefly mentioned the most common issues users have encountered so far. --- aspnetcore/migration/20_21.md | 43 +++++++++++-------- .../migration/20_21/sample/WebApp21.csproj | 4 +- 2 files changed, 28 insertions(+), 19 deletions(-) diff --git a/aspnetcore/migration/20_21.md b/aspnetcore/migration/20_21.md index 13ad2202dd92..432db6fe4a23 100644 --- a/aspnetcore/migration/20_21.md +++ b/aspnetcore/migration/20_21.md @@ -3,7 +3,7 @@ title: Migrate from ASP.NET Core 2.0 to 2.1 author: rick-anderson description: This article covers the basics of migrating an ASP.NET Core 2.0 app to 2.1. ms.author: riande -ms.date: 05/30/2018 +ms.date: 07/10/2018 uid: migration/20_21 --- # Migrate from ASP.NET Core 2.0 to 2.1 @@ -24,24 +24,28 @@ A quick way to get an overview of the changes in 2.1 is to: * 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. +This article provides an overview on migration to ASP.NET Core 2.1. It doesn't 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: +Update the project file: -* Change `netcoreapp2.0` to the 2.1 version, that is `netcoreapp2.1`. -* 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](xref:fundamentals/metapackage#migrate) and [Microsoft.AspNetCore.App metapackage](xref:fundamentals/metapackage-app). If you're targetting the .NET Framework: - - * Add individual package references instead of a meta package reference. +* Change the target framework to .NET Core 2.1 by updating the project file to `netcoreapp2.1`. +* Replace the package reference for `Microsoft.AspNetCore.All` with a package reference for `Microsoft.AspNetCore.App`. You may need to add dependencies that were removed from `Microsoft.AspNetCore.All`. For more information, see and . For apps that target the .NET Framework: + * Add individual package references instead of a metapackage reference. * Update each package reference to 2.1. -* Remove all references to `` elements for "Microsoft.AspNetCore", "Microsoft.VisualStudio", and "Microsoft.EntityFrameworkCore" packages. These tools have been replaced by global tools. +* Remove references to **<DotNetCliToolReference>** elements for the following packages. These tools are bundled by default in the .NET Core CLI and don't need to be installed separately. + * Microsoft.DotNet.Watcher.Tools (`dotnet watch`) + * Microsoft.EntityFrameworkCore.Tools.DotNet (`dotnet ef`) + * Microsoft.Extensions.Caching.SqlConfig.Tools (`dotnet sql-cache`) + * Microsoft.Extensions.SecretManager.Tools (`dotnet user-secrets`) +* Optional: you can remove the **<DotNetCliToolReference>** element for `Microsoft.VisualStudio.Web.CodeGeneration.Tools`. You can replace this tool with a globally installed version by running `dotnet tool install -g dotnet-aspnet-codegenerator`. -The following markup shows the template generated 2.0 *.csproj* project file: +The following markup shows the template-generated 2.0 project file: [!code-xml[Main](20_21/sample/WebApp20.csproj)] -The following markup shows the template generated 2.1 *.csproj* project file: +The following markup shows the template-generated 2.1 project file: [!code-xml[Main](20_21/sample/WebApp21.csproj)] @@ -52,14 +56,19 @@ ASP.NET Core includes the following shared runtimes: * [Microsoft.AspNetCore.App](xref:fundamentals/metapackage-app) * [Microsoft.AspNetCore.All](xref:fundamentals/metapackage) -Rules for projects targeting the shared runtime: +The version specified by the package reference is the *minimum required* version. For example, a project referencing the 2.1.1 versions of these packages won't run on a machine with only the 2.1.0 runtime installed. + +Known issues for projects targeting the shared runtime: + +* Using `Microsoft.AspNetCore.App` 2.1.0 with Entity Framework Core 2.1.1 causes NuGet restore failures due to package conflicts. The recommended solution is to upgrade `Microsoft.AspNetCore.App` to 2.1.1. For more information, see [Packages that share dependencies with Microsoft.AspNetCore.App cannot reference patch versions](https://github.com/aspnet/Universe/issues/1180). +* All projects that must use `Microsoft.AspNetCore.All` or `Microsoft.AspNetCore.App` should add a package reference for the package in the project file, even if they contain a project reference to another project using `Microsoft.AspNetCore.All` or `Microsoft.AspNetCore.App`. + + Example: -* 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 (``). -* 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 (``). - * 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 ``. -* 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. + - `MyApp` has a package reference to `Microsoft.AspNetCore.App`. + - `MyApp.Tests` has a project reference to `MyApp.csproj`. + + Add a package reference for `Microsoft.AspNetCore.App` to `MyApp.Tests`. For more information, see [Integration testing is hard to set up and may break on shared framework servicing](https://github.com/aspnet/Home/issues/3156). ## Changes to take advantage of the new code-based idioms that are recommended in ASP.NET Core 2.1 diff --git a/aspnetcore/migration/20_21/sample/WebApp21.csproj b/aspnetcore/migration/20_21/sample/WebApp21.csproj index 318eeb348cfc..a2b0da258b2a 100644 --- a/aspnetcore/migration/20_21/sample/WebApp21.csproj +++ b/aspnetcore/migration/20_21/sample/WebApp21.csproj @@ -6,8 +6,8 @@ - - + +