Provide CLI commands for investigating the contents and available workload set versions

baronfel commented 3 months ago

Now that we have workload sets, users have three questions about them that we can't easily answer:

what workload sets are available?
what's in workload set XYZ?
what workload set contains version 8.0.1 of Aspire?

We will provide CLI commands that enable users to learn the answers to all of those questions.

What workload set versions are available?

Workload sets are shipped as a specific NuGet package and are selected by users by version, either implicitly or explicitly. We should provide a command to list the top N versions of the workload set package available on the selected feeds so that users know what versions are available.

[x] provide a new subcommand for listing the versions: dotnet workload search versions
- This command will list package versions for the Microsoft.NET.Workloads.{SDKFeatureBand} of the currently-used SDK
- It will have a --take command to limit the number of versions returned (based on prior art from dotnet package search --take, I'm not personally a fan of this and would consider --count).
- It will have a --format <table|json> option and will emit the results as either a JSON array of strings or a terminal-formatted table using our existing helpers
[x] incorporate the same nuget version querying into tab-completion for dotnet workload install --version and dotnet workload update --version for workload sets

What's in workload set XYZ?

Users want to know what versions of the workloads are bundled in each workload set for a number of reasons. We'll tackle this in two parts:

[ ] include information about the bundled workload versions in a structured format in the package metadata for the workload set package - this will involve updating package authoring to read the manifests for the workloads that flow into this repo and writing them (probably as JSON) into the package release notes. We need a field that is present in package metadata so that we can use NuGet APIs for package metadata to list/retrieve data, instead of having to download the entire package.
[x] once that structured information is present, we need a new CLI command to list the information out: dotnet workload search sets <workload set version>
- [x] as above, tab completion for the argument should populate with versions of the workload set package
- [x] the command will have a --format <table|json> option that will emit the results as either a JSON array of objects describing each workload in the workload set, or as a table using our existing helpers

As an example of what this could look like, let's take the existing output from dotnet workload list, which lists the versions of workloads that are installed locally. This output is from my local Windows desktop, which is not configured to use workload sets:

$dotnet workload list

Installed Workload Id      Manifest Version                               Installation Source
----------------------------------------------------------------------------------------------------------------
aspire                     9.0.0-preview.2.24163.9/9.0.100-preview.1      VS 17.10.35027.167, VS 17.11.35111.106
android                    34.99.0-preview.1.151/9.0.100-preview.1        VS 17.11.35111.106
maui-windows               9.0.0-preview.1.9973/9.0.100-preview.1         VS 17.11.35111.106
maccatalyst                17.2.9088-net9-p1/9.0.100-preview.1            VS 17.11.35111.106
ios                        17.2.9088-net9-p1/9.0.100-preview.1            VS 17.11.35111.106

Use `dotnet workload search` to find additional workloads to install.

The major difference that the proposed "what's in workload set X" command would have compared to this is:

it would list all workloads in the set, not the installed subset
it would not need to list the Manifest Version because all listed workloads would have the same effective manifest version

What workload contains version X of component or workload Y?

AKA a reverse-lookup, inverting the previous command. Once we have the data to power the above command, we should be able to use it to look up the matching workload set version for a given workload version (e.g. Aspire 8.0.1).

[ ] create a new command dotnet workload search sets --component <component ID and version>, where <component ID and version> is a structure like <component@version> - for example Aspire@8.0.1.
- There are a bunch of alternatives here we should consider
- multiple components: dotnet workload search sets --component aspire@8.0.1 --component maui-android@17.2.1
  - could also do multiple args on a single --component option easily as well
- search criteria at root: dotnet workload search sets aspire@8.0.1 maui-android@17.2.1
  - potentially restricts the CLI grammar in the future
- searching more than just workloads: dotnet workload search versions xcode@9.0
  - would require the workload-versions repo injecting more structured data from the individual workloads, which would require workload authors to provide that structured data at package construction

This question is the least fleshed-out but we hope this gives enough of an idea to have a discussion.

Automatically install a workload set that contains a given workload version

Building on the previous 3 commands, users should be able to do something like dotnet workload install aspire@8.0.1 maui@46.8 and the tooling should find the workload set (or sets) that contains both of those and install that workload set. Potentially prompting the user to make a choice if multiple valid sets are found.

Open questions

What should the main noun used for these commands be? Above I have used sets but @dsplaisted's suggestion of versions is also very reasonable and has the upside of not introducing the workload sets concept to the CLI grammar or to users.
What is the exact structure of the content that we will embed into the workload sets manifest package and the workload packages for describing their dependencies?
What is a reasonable place to store this data on the NuGet package metadata?
- Right now we are investigating the release notes field
prior art on the id@version syntax exists in the template install command: <id>::<version>

dsplaisted commented 3 months ago

Thanks for writing this! I'd suggest considering dotnet workload list versions instead of dotnet workload list sets, avoiding "workload sets" as a user-facing term.

JonDouglas commented 3 months ago

Looks great. Just a few thoughts on my end:

The xcode@9.0 syntax seems like a great shorthand that could be a streamlined syntax if no parameter is provided for --version and --component.
I have a hard time visualizing how this would look like as a table, which I think would help provide a better picture of what this does.
Consider using a cheap quickpulse survey on naming challenges to get a quick signal between naming directions.
Trying to wrap my head around the What is a reasonable place to store this data on the NuGet package metadata? question still. It sounds like workload metadata would go into the release notes field? That doesn't seem ideal as release notes should be used for changes to the workload itself?

dotnet / sdk