Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the migration docs to remove instructions for versionless package references #7543

Merged
merged 8 commits into from Jul 10, 2018
Merged

Update the migration docs to remove instructions for versionless package references #7543

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7f7848a
Update the migration docs to remove instructions for versionless pack…
Jul 10, 2018
012a945
Language updates
guardrex Jul 10, 2018
19cd852
Update 20_21.md
natemcmaster Jul 10, 2018
4318c52
Update 20_21.md
natemcmaster Jul 10, 2018
1f10313
Fewer "add a"'s
natemcmaster Jul 10, 2018
a758e59
Update 20_21.md
natemcmaster Jul 10, 2018
a705422
Update 20_21.md
natemcmaster Jul 10, 2018
0049590
Minor tweaks
scottaddie Jul 10, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
43 changes: 26 additions & 17 deletions aspnetcore/migration/20_21.md
View file
Open in desktop
Expand Up @@ -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
Expand All @@ -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 `<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](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 `<TargetFramework>netcoreapp2.1</TargetFramework>`.
* 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 <xref:fundamentals/metapackage#migrate> and <xref:fundamentals/metapackage-app>. 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 `<DotNetCliToolReference>` elements for "Microsoft.AspNetCore", "Microsoft.VisualStudio", and "Microsoft.EntityFrameworkCore" packages. These tools have been replaced by global tools.
* Remove references to **&lt;DotNetCliToolReference&gt;** 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 **&lt;DotNetCliToolReference&gt;** 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)]

Expand All @@ -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 (`<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.
- `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

Expand Down
4 changes: 2 additions & 2 deletions aspnetcore/migration/20_21/sample/WebApp21.csproj
View file
Open in desktop
Expand Up @@ -6,8 +6,8 @@
</PropertyGroup>

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

</Project>