Sdk: Provide fwlink in the warning about obsolete DotNetCliToolReference that points to good documentation about global tools

[balachir]

Steps to reproduce

With VS 15.7 + CLI for .NET Core 2.1 (CLI 2.1.300 or higher) installed,

1. Open ASP.NET Core 2.0 project that was created using a previous version of the CLI
2. View Error list or build

Actual behavior

You see the warnings below

Expected behavior

Warning should include an fwlink that can be clicked and take you to good documentation about why the tools are obsolete and what is the mitigation

[livarcocc]

@KathleenDollard @danroth27 @leecow who can provide me with an updated message that contains the appropriate forward link?

[KathleenDollard]

Suggest:

Using DotNetCliToolReference to reference 'Microsoft.EntityFrameworkCore.Tools.DotNet' is obsolete and can be removed from this project. This tool is bundled by default in the .NET Core SDK. More info on tool usage.

[balachir]

Thanks Kathleen. Couple of comments:

1. For ASP.NET Core 2.0 projects, the text looks fine to me. One suggestion: the link More info on tool usage should be an fwlink rather than point directly to https://aka.ms/global-tools.

   • The https://aka.ms/global-tools link points to very generic documentation about .NET Core CLI tools. Given a lot of ASP.NET Core 2.0 developers will see this warning about DotNetCliToolReference in their csproj becoming obsolete, it will be helpful if we can get the fwlink to point to some customized documentation that explains to users why DotNetCliToolReference entries are now obsolete and what are the next steps that the user should take.

2. For ASP.NET Core 1.1 projects, the message that Kathleen proposed is incorrect because the tools cannot be removed from the project for this case. I believe we should have a separate message customized for ASP.NET Core 1.1 projects - that's why I opened a separate issue https://github.com/dotnet/cli/issues/9120 for the 1.1 case. @livarcocc, should we re-activate https://github.com/dotnet/cli/issues/9120?

[KathleenDollard]

@balachir Thank you

Using DotNetCliToolReference to reference 'Microsoft.EntityFrameworkCore.Tools.DotNet' is not needed for .NET Core 2.1 and can be removed from this project because this tool is bundled by default in the .NET Core SDK. .NET Core 1.1 projects should pin the SDK in global.json. See [[]]

@mairaw I'm working on text for docs. Let's use a separate link. Is there suggested text to introduce a link?

[balachir]

I discussed some more with Kathleen offline on Skype, and she and I are on the same page now.

1. For ASP.NET Core 2.0 projects: we can keep the text below. Note that the "More info on tool usage" part is an fwlink. @KathleenDollard, can you provide a new fwlink to use here?

Using DotNetCliToolReference to reference 'Microsoft.EntityFrameworkCore.Tools.DotNet' is obsolete and can be removed from this project. This tool is bundled by default in the .NET Core SDK. [More info on tool usage.] (fwlink)

1. For ASP.NET Core 1.1 projects: Kathleen and I agreed that this should be an error rather than a warning, and the message should be different. I went ahead and re-activated dotnet/cli#9120 and proposed an error message there.

[KathleenDollard]

Using DotNetCliToolReference to reference 'Microsoft.EntityFrameworkCore.Tools.DotNet' is obsolete and can be removed from this project. This tool is bundled by default in the .NET Core SDK. [See] (https://aka.ms/dotnetclitools-in-box)

[natemcmaster]

If you haven't seen it already, checkout https://github.com/aspnet/Announcements/issues/290. This contains details on the change and instructions on how to upgrade.

[KathleenDollard]

This scenario faced by the user is more complicated. It's difficult for us to make recommendations by tool and the recommendation may vary by version of the target of the tool, which we don't know. Thus, I suggest a simple message and a complete explanation in help.

The tool 'Microsoft.EntityFrameworkCore.Tools.DotNet' is now included in the .NET Core SDK. Here is information on resolving this warning.

[KathleenDollard]

Due to complexity and the fact the message does not convey a specific action, I am including the draft of the help text I will propose for this link in help (expect structural and grammatical changes):

Certain tools now bundled in .NET Core SDK 2.1.300

Starting with .NET Core SDK 2.1.300 (which is part of .NET Core 2.1), some tools previously installed by adding DotNetCliToolReference elements to your project file are bundled with the SDK. These newly bundled tools are:

• dotnet-ef
• dotnet-watch
• dotnet-user-secrets
• dotnet-sql-cache

In previous versions of the .NET Core SDK, you made these tools available by include a DotNetCliToolReference in your project file, such as:

<DotNetCliToolReference Include="Microsoft.EntityFrameworkCore.Tools.DotNet" Version="2.0.0" />

Since this entry is not used by .NET Core SDK 2.1.300, you will receive this warning:

The tool 'Microsoft.EntityFrameworkCore.Tools.DotNet' is now included in the .NET Core SDK. Here is information on resolving this warning.

Depending on the tool, one of the sections below will show you how to resolve this warning:

Entity Framework versions 1.0 and 1.1

Entity Framework version 2.0 is compatible with the Entity Framework tools included in .NET Core SDK 2.1.300. For projects using Entity Framework 2.0, skip to the next section.

Entity Framework versions 1.0 and 1.1 are not compatible with the version of Entity Framework that is bundled with .NET Core SDK 2.1.300. In order to use earlier versions of Entity Framework, you must specify a version of the .NET Core SDK 2.1.200 or below by using a global.json file. This file is normally included in the solution directory (one above the project).

This link has more information about global.json.

Bundled tools, except Entity Framework 1.0 and 1.1

Bundled tools, other than Entity Framework 1.0 and 1.1, replace those specified in the project file. Because these <DotNetCLITool> entries are not used, they should be removed from your project file after your team has converted to .NET Core SDK 2.1.300.

Summary

| Name | Previous Tool Name | Previous Package Name | Action |
|----------------|---------------------|----------------------------------------------|--------|
| EF Tools v1.0 | dotnet-ef | Microsoft.EntityFrameworkCore.Tools.DotNet | 1 |
| EF Tools v1.1 | dotnet-ef | Microsoft.EntityFrameworkCore.Tools.DotNet | 1 |
| EF Tools v2.0+ | dotnet-ef | Microsoft.EntityFrameworkCore.Tools.DotNet | 2 |
| DotNet Watch | dotnet-watch | Microsoft.DotNet.Watcher.Tools | 2 |
| Secret Manager | dotnet-user-secrets | Microsoft.Extensions.SecretManager.Tools | 2 |
| Sql Cache | dotnet-sql-cache | Microsoft.Extensions.Caching.SqlConfig.Tools | 2 |

1. Pin to .NET Core SDK 2.1.200 or below via a global.json file.
2. Remove <DotNetCliToolReference> from the project file.

[KathleenDollard]

@divega @ajcvickers @bricelam

[ajcvickers]

Looks fine to me.

[divega]

Looks good to me too.

[livarcocc]

@KathleenDollard can you confirm the final message that we are supposed to use here. This is a long thread that has evolved over time and it is not clear to me what we should use.

[KathleenDollard]

@balachir

Why an fwlink here rather than an aka.ms link which could be more readable? At your request here is an fwlink. Livar, go with this one unless you can wait for Bala's answer.

The tool 'Microsoft.EntityFrameworkCore.Tools.DotNet' is now included in the .NET Core SDK. Information on resolving this warning is at (https://go.microsoft.com/fwlink/?linkid=873062).

[livarcocc]

I don't believe this is the right message. This regards all tools that are now bundled: watch, dev-certs, sql-secrets, etc. ef is a special case among these that we should special case, but we can't make this message just about ef.

cc @natemcmaster

[KathleenDollard]

So sorry. you are correct. We know the name of the tool, correct? It was in the old message

The tool '' is now included in the .NET Core SDK. Information on resolving this warning is at (https://go.microsoft.com/fwlink/?linkid=873062).

[KathleenDollard]

Sorry to change this again, but if it's not too late, switch back to the aka.ms reference. This is due to a conversation with @Andrew-MSFT on using readable links when we plan for people to type them. If this is inconsistent with other warnings, or there's another issue, let me know.

The tool '' is now included in the .NET Core SDK. Information on resolving this warning is at (https://aka.ms/dotnetclitools-in-box).

[edwardaskew]

Forgive me if I'm being dumb but I just got this warning and https://aka.ms/dotnetclitools-in-box redirects to https://github.com/dotnet/core/blob/master/release-notes/2.1/Preview/2.1.0-preview2-known-issues.md which didn't actually help much. It wasn't until I googled the message and arrived at this issue that I actually worked out that the issue was old DotNetCliToolReference elements in the project file.

I don't know whether there is somewhere better to redirct to (https://go.microsoft.com/fwlink/?linkid=873062 redirects to https://docs.microsoft.com/en-gb/dotnet/core/tools/?tabs=netcore2x which doesn't seem massively helpful either).

[natemcmaster]

@edwardaskew not a dumb question at all. Sometimes we put aka.ms links into our code before docs are ready, but I think docs are done now.

@KathleenDollard @mairaw I'm assuming https://aka.ms/dotnetclitools-in-box should be updated to https://docs.microsoft.com/en-us/dotnet/core/migration/20-21, right?

[KathleenDollard]

@mairaw or @BillWagner

I believe the text we want for the topic is here and the fwlink ready and being displayed in help. How can we get the dots connected on this, because this will be a very common warning for customers.

[mike1880]

And here we are more than a month later and I'm in exactly the same position as @edwardaskew.

[KathleenDollard]

@mike1880 Thanks for letting us know. I'm checking on this.

[mairaw]

I've created a docs issue for this at https://github.com/dotnet/docs/issues/6802 and we'll take care of this ASAP.

[mairaw]

Just to follow up on this, the link has now been updated: https://aka.ms/dotnetclitools-in-box

Any other feedback re. this, please create a new issue on the dotnet/docs repo.