[Spec] NuGet Build Integrated Project handling of floating versions and ranges in Visual Studio Client

Issues

#3788 - NETCore PackageReference with a star is displayed under the updates tab

#3101 - NuGet Visual Studio UI shows floating versions incorrectly

#3109 - NuGet UI cannot interact with version ranges with no minimum

Problem

In a build integrated NuGet project a user can specify a range or a floating version as a package version. The current behavior of the package manager UI inside of Visual Studio has no support for this. If a user indicates a floating version or a range in any of the packages (e.g. 10.0.*) the UI will take its minimum version possible (e.g. 10.0.0) and show it as if it is installed, even though the actual resolved version could be different. In the following example, the package reference specifies 3.7.*, and the resolved version (found in the assets file) is 3.7.1, nevertheless the UI shows that the installed version is 3.7.0, which is misleading.

UI for list item at project level

UI for detail control at project level

UI for detail control at solution level

This scenario can also be problematic if the calculated version doesn't exist, because there are several incorrect indications of the package version (both at solution and at project level), and also the list item will not load the correct metadata for the package. In the example below the specified version was 10.0.* and it was resolved to 10.0.3, but version 10.0.0 doesn't exist for this package.

UI for list item at project level

UI for detail control at project level

Solution

The current behavior of the Visual Studio client at a project level with packages using non-floating versions is to show the version installed on the right on the list item, on the "Installed" box in the detail view and bold in the "Version" dropdown in the detail view for each dependency.

UI for list item at project level

The updates are always suggested based on this installed/resolved version.

UI for list item at project level

UI for detail control at project level

In the case of the solution level, the version installed for each project is shown in the project list, in the "Installed" box and bold in the "Version" dropdown in the detail view for each dependency.

UI for detail control at solution level

Also when a package is updated the version in the package reference is updated with the version just installed.

The proposed solution involves updating the client (in both, the project and the solution level UI) to get the actual resolved version for each package from the assets file instead of calculating the minimum version, therefore the version number shown will always portrait the actual version installed.

For the manager UI at the project level, this involves updating the version on the right in the list item, the version on the "Installed" section of the detail view and the bold version of the "Version" dropdown in the detail view to show the actual version resolved, not a minimum calculated by the client.

In the case of the manager UI at the solution level, this involves updating the version on the project list for each project, the "Installed" section of the detail view and the bold version of the "Version" dropdown in the detail view to show the version resolved.

This solution also involves that when a package is updated and the package reference specifies a floating version or a range, this reference will only be updated if the new version installed doesn't fall inside of the range previously specified.

Taking this updates in consideration, there are some scenarios that are relevant and are presented below.

Scenarios

• There is no project.assets.json file.
• The project has multiple target frameworks and more than one of these have the same package with different versions.
• Updating a reference and running restore when the UI is open (changing resolved version)

No project.assets.json file

When a project doesn't have a project.assets.json file it means that restore hasn't finished running, therefore the packages haven't been resolved. For this scenario NuGet Client doesn't have enough information to get a resolved version for each package. Therefore the behavior will fall back to calculating the minimum version possible for ranges or floating versions. This will still preserve issues when this version doesn't exist or if the range doesn't have a minimum version.

Multiple target frameworks with different versions of the same package

This scenario is important because we are updating the version of each package with the actual resolved version. In this case, the package will be resolved to different versions. The propose solution suggests that the minimum of the resolved package versions is taken and shown in the UI. The behavior for updates should not change in this scenario.

Changing resolved version of a package while UI open

The UI shouldn't update until the user clicks the refresh button explicitly. Once this button has been clicked, the new project.assets.json file should be read and the values for each package version should be updated in the aforementioned places in the detail and list view for the manager UI.