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 6 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
34 changes: 19 additions & 15 deletions aspnetcore/migration/20_21.md
View file
Open in desktop
Expand Up @@ -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 .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 all references to **&lt;DotNetCliToolReference&gt;** elements for `Microsoft.AspNetCore`, `Microsoft.VisualStudio`, and `Microsoft.EntityFrameworkCore` packages. These tools have been replaced by global tools.
Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I've seen a format of ... for example ... Microsoft.VisualStudio.*.

Can it just read ...

Remove all references to <DotNetCliToolReference> elements.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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

* Microsoft.EntityFrameworkCore.Tools.DotNet
* Microsoft.Extensions.Caching.SqlConfig.Tools
* Microsoft.Extensions.SecretManager.Tools
* Microsoft.DotNet.Watcher.Tools

You can also remove a DotNetCliToolReference to Microsoft.VisualStudio.Web.CodeGeneration.Tools can be removed if you also run dotnet tool install -g dotnet-aspnet-codegenerator to replace it.


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 +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 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>