Support package@version syntax for dotnet workload search/update/install version Fixes #42367 (#45156)

Fixes #42367

Using dotnet workload search version, you should now be able to provide package@version as an argument, and it will find the highest-valued workload version that has that package at that version.

Sample when no such workload version was found:
image

When 3 were found:
image

(Note that the other two were 9.0.200.1 and 9.0.200, so this is the highest version number.)

There are three total uses of dotnet workload search version that previously existed:
Without any argument, it lists out the most recent SDKs (in the current feature band):

dotnet workload search version --format json

image

When provided with a workload version, it lists out all the workloads in that workload version:

dotnet workload search version 9.0.201

image

(Note that this was a manually created 9.0.201 version, so those versions do not align with a real one.)

And as mentioned earlier, when one or more workloads along with versions (concatenated with '@'), it finds a workload version that includes all of the provided workloads at the associated versions.

dotnet workload search version [email protected] [email protected]

image

This PR also dramatically changes the help text either when you use dotnet workload search version -? or when you mistype a command. It now looks like this:
image

Author: Forgind

src/Cli/dotnet/CommonLocalizableStrings.resx

@@ -734,6 +734,10 @@ The default is 'false.' However, when targeting .NET 7 or lower, the default is
   <data name="ResponseFileNotFound" xml:space="preserve">
     <value>Response file '{0}' does not exist.</value>
   </data>
+  <data name="ShortWorkloadSearchVersionDescription" xml:space="preserve">
+    <value>Search for available workload versions or what comprises a workload version. Use 'dotnet workload search version --help' for more information.</value>
+    <comment>{Locked="dotnet workload search version --help"}</comment>
+  </data>
   <data name="CorruptSolutionProjectFolderStructure" xml:space="preserve">
     <value>The solution file '{0}' is missing EndProject tags or has invalid child-parent project folder mappings around project GUID: '{1}'. Manually repair the solution or try to open and save it in Visual Studio."</value>
   </data>

src/Cli/dotnet/NugetPackageDownloader/NuGetPackageDownloader.cs

@@ -567,7 +567,8 @@ await Task.WhenAll(
 
                 if (stableVersions.Any())
                 {
-                    return stableVersions.OrderByDescending(r => r.package.Identity.Version).Take(numberOfResults);
+                    var results = stableVersions.OrderByDescending(r => r.package.Identity.Version);
+                    return numberOfResults > 0 /* 0 indicates 'all' */ ? results.Take(numberOfResults) : results;
                 }
             }
 

src/Cli/dotnet/Parser.cs

@@ -237,6 +237,8 @@ private static void SetHelpCustomizations(HelpBuilder builder)
                     };
                     builder.CustomizeSymbol(option, secondColumnText: descriptionCallback);
                 }
+
+                builder.CustomizeSymbol(WorkloadSearchVersionsCommandParser.GetCommand(), secondColumnText: CommonLocalizableStrings.ShortWorkloadSearchVersionDescription);
             }
 
             public void additionalOption(HelpContext context)

src/Cli/dotnet/commands/InstallingWorkloadCommand.cs

@@ -2,12 +2,6 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System.CommandLine;
-using System.IO;
-using System.Linq;
-using System.Net.Http.Json;
-using System.Runtime.CompilerServices;
-using System.Text.Json;
-using System.Text.Json.Nodes;
 using Microsoft.Deployment.DotNet.Releases;
 using Microsoft.DotNet.Cli;
 using Microsoft.DotNet.Cli.Commands.DotNetWorkloads;
@@ -16,6 +10,7 @@
 using Microsoft.DotNet.ToolPackage;
 using Microsoft.DotNet.Workloads.Workload.History;
 using Microsoft.DotNet.Workloads.Workload.Install;
+using Microsoft.DotNet.Workloads.Workload.Search;
 using Microsoft.DotNet.Workloads.Workload.Update;
 using Microsoft.Extensions.EnvironmentAbstractions;
 using Microsoft.NET.Sdk.WorkloadManifestReader;
@@ -41,7 +36,7 @@ internal abstract class InstallingWorkloadCommand : WorkloadCommandBase
         protected readonly string _fromRollbackDefinition;
         protected int _fromHistorySpecified;
         protected bool _historyManifestOnlyOption;
-        protected string _workloadSetVersionFromCommandLine;
+        protected IEnumerable<string> _workloadSetVersionFromCommandLine;
         protected string _globalJsonPath;
         protected string _workloadSetVersionFromGlobalJson;
         protected readonly PackageSourceLocation _packageSourceLocation;
@@ -55,7 +50,7 @@ internal abstract class InstallingWorkloadCommand : WorkloadCommandBase
 
         protected bool UseRollback => !string.IsNullOrWhiteSpace(_fromRollbackDefinition);
         protected bool FromHistory => _fromHistorySpecified != 0;
-        protected bool SpecifiedWorkloadSetVersionOnCommandLine => !string.IsNullOrWhiteSpace(_workloadSetVersionFromCommandLine);
+        protected bool SpecifiedWorkloadSetVersionOnCommandLine => _workloadSetVersionFromCommandLine?.Any() == true;
         protected bool SpecifiedWorkloadSetVersionInGlobalJson => !string.IsNullOrWhiteSpace(_workloadSetVersionFromGlobalJson);
         protected WorkloadHistoryState _WorkloadHistoryRecord
         {
@@ -186,7 +181,7 @@ protected void UpdateWorkloadManifests(WorkloadHistoryRecorder recorder, ITransa
             {
                 // This is essentially the same as updating to a specific workload set version, and we're now past the error check,
                 // so we can just use the same code path.
-                _workloadSetVersionFromCommandLine = _WorkloadHistoryRecord.WorkloadSetVersion;
+                _workloadSetVersionFromCommandLine = [_WorkloadHistoryRecord.WorkloadSetVersion];
             }
             else if ((UseRollback || FromHistory) && updateToLatestWorkloadSet)
             {
@@ -214,7 +209,39 @@ protected void UpdateWorkloadManifests(WorkloadHistoryRecorder recorder, ITransa
                 }
             }
 
-            string resolvedWorkloadSetVersion = _workloadSetVersionFromGlobalJson ??_workloadSetVersionFromCommandLine;
+            string resolvedWorkloadSetVersion = null;
+
+            if (_workloadSetVersionFromCommandLine?.Any(v => v.Contains('@')) == true)
+            {
+                var versions = WorkloadSearchVersionsCommand.FindBestWorkloadSetsFromComponents(
+                    _sdkFeatureBand,
+                    _workloadInstaller is not NetSdkMsiInstallerClient ? _workloadInstaller : null,
+                    _sdkFeatureBand.IsPrerelease,
+                    PackageDownloader,
+                    _workloadSetVersionFromCommandLine,
+                    _workloadResolver,
+                    numberOfWorkloadSetsToTake: 1);
+
+                if (versions is null)
+                {
+                    return;
+                }
+                else if (!versions.Any())
+                {
+                    Reporter.WriteLine(Update.LocalizableStrings.NoWorkloadUpdateFound);
+                    return;
+                }
+                else
+                {
+                    resolvedWorkloadSetVersion = versions.Single();
+                }
+            }
+            else if (SpecifiedWorkloadSetVersionOnCommandLine)
+            {
+                resolvedWorkloadSetVersion = _workloadSetVersionFromCommandLine.Single();
+            }
+
+            resolvedWorkloadSetVersion = _workloadSetVersionFromGlobalJson ?? resolvedWorkloadSetVersion;
             if (string.IsNullOrWhiteSpace(resolvedWorkloadSetVersion) && !UseRollback && !FromHistory)
             {
                 _workloadManifestUpdater.UpdateAdvertisingManifestsAsync(_includePreviews, updateToLatestWorkloadSet, offlineCache).Wait();
@@ -441,9 +468,10 @@ protected IEnumerable<WorkloadId> WriteSDKInstallRecordsForVSWorkloads(IEnumerab
 
     internal static class InstallingWorkloadCommandParser
     {
-        public static readonly CliOption<string> WorkloadSetVersionOption = new("--version")
+        public static readonly CliOption<IEnumerable<string>> WorkloadSetVersionOption = new("--version")
         {
-            Description = Strings.WorkloadSetVersionOptionDescription
+            Description = Strings.WorkloadSetVersionOptionDescription,
+            AllowMultipleArgumentsPerToken = true
         };
 
         public static readonly CliOption<bool> PrintDownloadLinkOnlyOption = new("--print-download-link-only")

src/Cli/dotnet/commands/dotnet-workload/install/IInstaller.cs

@@ -14,6 +14,8 @@ internal interface IInstaller : IWorkloadManifestInstaller
     {
         int ExitCode { get; }
 
+        WorkloadSet GetWorkloadSetContents(string workloadVersion);
+
         void InstallWorkloads(IEnumerable<WorkloadId> workloadIds, SdkFeatureBand sdkFeatureBand, ITransactionContext transactionContext, DirectoryPath? offlineCache = null);
 
         void RepairWorkloads(IEnumerable<WorkloadId> workloadIds, SdkFeatureBand sdkFeatureBand, DirectoryPath? offlineCache = null);

src/Cli/dotnet/commands/dotnet-workload/install/LocalizableStrings.resx

@@ -327,7 +327,7 @@
   </data>
   <data name="CannotUseSkipManifestWithGlobalJsonWorkloadVersion" xml:space="preserve">
     <value>Cannot use the {0} option when workload version is specified in global.json.  Remove the {0} option, or remove the 'workloadVersion' element from {1}.</value>
-    <comment>"workloadVersion" and "global.json" are literal values and should not be translated.</comment>
+    <comment>{Locked="workloadVersion"} Locked={"global.json"}</comment>
   </data>
   <data name="SkipSignCheckOptionDescription" xml:space="preserve">
     <value>Skip signature verification of workload packages and installers.</value>
@@ -348,7 +348,7 @@
     <value>Manifest MSI not found in NuGet package {0}</value>
   </data>
   <data name="WorkloadSetVersionOptionDescription" xml:space="preserve">
-    <value>Update to the specified workload version.</value>
+    <value>A workload version to display or one or more workloads and their versions joined by the '@' character.</value>
   </data>
   <data name="NewWorkloadSet" xml:space="preserve">
     <value>Installing workload version {0}.</value>
@@ -365,4 +365,8 @@
   <data name="FailedToInstallWorkloadSet" xml:space="preserve">
     <value>Failed to install workload version {0}: {1}</value>
   </data>
+  <data name="CannotSpecifyVersionAndWorkloadIdsByComponent" xml:space="preserve">
+    <value>Cannot specify a workload version using the --version option while also specifying versions to install using workload@version syntax.</value>
+    <comment>{Locked="--version"}</comment>
+  </data>
 </root>

src/Cli/dotnet/commands/dotnet-workload/install/NetSdkMsiInstallerClient.cs

@@ -1183,5 +1183,10 @@ void IInstaller.UpdateInstallMode(SdkFeatureBand sdkFeatureBand, bool? newMode)
             string newModeString = newMode == null ? "<null>" : newMode.Value ? WorkloadConfigCommandParser.UpdateMode_WorkloadSet : WorkloadConfigCommandParser.UpdateMode_Manifests;
             Reporter.WriteLine(string.Format(LocalizableStrings.UpdatedWorkloadMode, newModeString));
         }
+
+        // This method should never be called for this kind of installer. It is challenging to get this information from an MSI
+        // and totally unnecessary as the information is identical from a file-based installer. It was added to IInstaller only
+        // to facilitate testing. As a consequence, it does not need to be implemented.
+        public WorkloadSet GetWorkloadSetContents(string workloadVersion) => throw new NotImplementedException();
     }
 }

src/Cli/dotnet/commands/dotnet-workload/install/WorkloadInstallCommand.cs

@@ -11,8 +11,6 @@
 using Microsoft.NET.Sdk.WorkloadManifestReader;
 using NuGet.Common;
 using NuGet.Versioning;
-using static Microsoft.NET.Sdk.WorkloadManifestReader.WorkloadResolver;
-using System.Text;
 
 namespace Microsoft.DotNet.Workloads.Workload.Install
 {
@@ -39,7 +37,22 @@ public WorkloadInstallCommand(
                   tempDirPath: tempDirPath)
         {
             _skipManifestUpdate = skipWorkloadManifestUpdate ?? parseResult.GetValue(WorkloadInstallCommandParser.SkipManifestUpdateOption);
-            _workloadIds = workloadIds ?? parseResult.GetValue(WorkloadInstallCommandParser.WorkloadIdArgument).ToList().AsReadOnly();
+            var unprocessedWorkloadIds = workloadIds ?? parseResult.GetValue(WorkloadInstallCommandParser.WorkloadIdArgument);
+            if (unprocessedWorkloadIds?.Any(id => id.Contains('@')) == true)
+            {
+                _workloadIds = unprocessedWorkloadIds.Select(id => id.Split('@')[0]).ToList().AsReadOnly();
+                if (SpecifiedWorkloadSetVersionOnCommandLine)
+                {
+                    throw new GracefulException(LocalizableStrings.CannotSpecifyVersionAndWorkloadIdsByComponent, isUserError: true);
+                }
+
+                _workloadSetVersionFromCommandLine = unprocessedWorkloadIds;
+            }
+            else
+            {
+                _workloadIds = unprocessedWorkloadIds.ToList().AsReadOnly();
+            }
+
             var resolvedReporter = _printDownloadLinkOnly ? NullReporter.Instance : Reporter;
 
             _workloadInstaller = _workloadInstallerFromConstructor ??