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.
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
Update the migration docs to remove instructions for versionless package references #7543
Changes from 4 commits
7f7848a
012a945
19cd852
4318c52
1f10313
a758e59
a705422
0049590
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -28,20 +28,19 @@ This article provides an overview on migration to ASP.NET Core 2.1. It does not | |
|
||
## 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 2.1, `<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 all references to **<DotNetCliToolReference>** elements for `Microsoft.AspNetCore`, `Microsoft.VisualStudio`, and `Microsoft.EntityFrameworkCore` packages. These tools have been replaced by global tools. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Are these package name prefixes? If so, let's state that to make it clearer. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm not sure I've seen a format of ... for example ... Can it just read ...
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. It would be better to be more specific. Only these can be removed without further action
You can also remove a DotNetCliToolReference to Microsoft.VisualStudio.Web.CodeGeneration.Tools can be removed if you also run |
||
|
||
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 +51,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. If a project references the 2.1.1 version of these packages, the app produced won't run on a machine that only has 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 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). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @natemcmaster See what I mean? 😄 That's ok ... more free 🍺 for Scott. |
||
|
||
## Changes to take advantage of the new code-based idioms that are recommended in ASP.NET Core 2.1 | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
2.1, --> .NET Core 2.1: