[Breaking change]: Enable users to install unlisted version of tool if specify the exact match of the version of the tool

[JL03-Yue]

Description

dotnet/sdk#36021

The change provides a feature to allow users to install the unlisted version but only if the user specify the exact match, i.e. [version]. (referred to NuGet package version reference).

Version

.NET 8 GA

Previous behavior

In .NET 8 we made a breaking change that changes the current .NET tool installation mechanism from restore a local temporary project to downloading the .NET tool from NuGet. This change was introduced because this previous mechanism has number of side effects, often show up as flaky restore errors because MSBuild concepts like Directory.Build.props, or other heirarchical notions, pollute the restore. However, this change disabled users from installing unlisted tools

New behavior

The new change allows users to install unlisted tools if specifying exact match of the version, i.e. [version].

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

#35566

The change of using NuGet API for downloading tools disabled users from installing unlisted tools. Previously, users were able to install unlisted tools per fix in dotnet/sdk#28951. However, since the mechanism of tool installation are changed, the unlisted tools' downloading are disabled by default. For users, installing unlisted tools are a useful method because it provides clarity and simplicity for those who write tools independently or do not share the tools to the public.

Recommended action

N/A

Feature area

SDK

Affected APIs

No response

---

Associated WorkItem - 177286

[dsplaisted]

I've made some suggested edits to this breaking change notice, see below. FYI @gewarren

Description

The dotnet tool install commands will no longer install tools from unlisted versions of NuGet packages, unless the version to install is specified on as an exact version surrounded with brackets, for example --version [5.0.0].

dotnet/sdk#36021

The change provides a feature to allow users to install the unlisted version but only if the user specify the exact match, i.e. [version]. (referred to NuGet package version reference).

Version

.NET 8 GA

Previous behavior

Previously, when installing .NET tools, the .NET SDK would install tools (and versions of tools) without considering whether the tool package was unlisted.

New behavior

Unlisted tool versions will not be installed by default, unless the exact version is specified with --version [version].

Type of breaking change

.NET CLI behavior change - dotnet commands behave differently with a new SDK.

Reason for change

We believe the correct default behavior is to ignore unlisted packages when installing tools. See dotnet/sdk#24037 and dotnet/sdk#32092.

Recommended action

To install an unlisted tool, specify the exact version of the tool surrounded with brackets, for example --version [5.0.0].

Feature area

SDK

Affected APIs

No response