Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
5 of 7 tasks
Tracked by #30008
baronfel opened this issue Jul 25, 2024 · 3 comments
Closed
5 of 7 tasks
Tracked by #30008
Assignees
Labels
Area-CLI Area-Workloads cli-ux Issues and PRs that deal with the UX of the CLI (exit codes, log output, verbs/options, and so on) needs design untriaged Request triage from a team member User Story A single user-facing feature. Can be grouped under an epic.

Comments

@baronfel
Copy link
Member

baronfel commented Jul 25, 2024

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.

  • 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
  • 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.
  • once that structured information is present, we need a new CLI command to list the information out: dotnet workload search sets <workload set version>
    • as above, tab completion for the argument should populate with versions of the workload set package
    • 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 [email protected].
    • There are a bunch of alternatives here we should consider
      • multiple components: dotnet workload search sets --component [email protected] --component [email protected]
        • could also do multiple args on a single --component option easily as well
      • search criteria at root: dotnet workload search sets [email protected] [email protected]
        • potentially restricts the CLI grammar in the future
      • searching more than just workloads: dotnet workload search versions [email protected]
        • 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 [email protected] [email protected] 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.

If multiple workloads are specified, the workload set used must satisfy all of them.

We should explicitly show in the usage section of the CLI help that there are two modes of the dotnet workload install command - one for workload sets and one for workloads - this will require customizing the help layout, and that's something we've wanted in several other scenarios.

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>
@ghost ghost added Area-Workloads untriaged Request triage from a team member labels Jul 25, 2024
@baronfel baronfel changed the title Design for including workload change details with the workload sets Provide CLI commands for investigating the contents and available workload set versions Jul 25, 2024
@baronfel baronfel added User Story A single user-facing feature. Can be grouped under an epic. Area-CLI cli-ux Issues and PRs that deal with the UX of the CLI (exit codes, log output, verbs/options, and so on) labels Jul 25, 2024
@dsplaisted
Copy link
Member

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
Copy link

Looks great. Just a few thoughts on my end:

  1. The [email protected] syntax seems like a great shorthand that could be a streamlined syntax if no parameter is provided for --version and --component.
  2. 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.
  3. Consider using a cheap quickpulse survey on naming challenges to get a quick signal between naming directions.
  4. 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?

Forgind added a commit that referenced this issue Aug 29, 2024
Progress on #42367

This adds three new parameters to the dotnet workload list command: version, --take, and --format. If version is specified, it will print the most recent `--take` workload sets (within the feature band; default (or if you specify a value < 1) is 5) and output them in --format (which can be json or csv; default (unspecified or other) is to put each version on its own line).

```terminal
> dotnet workload search version
9.0.105
9.0.104
9.0.103
9.0.102
9.0.101
```

```terminal
> dotnet workload search version --format json --take 2
[{ "workloadVersion": "9.0.105"},{ "workloadVersion": "9.0.104" }]
```

### Converting the json output to lines/other formats

#### sh (with jq)
```bash
> dotnet workload search version --format json --take 2 | jq 'map(.workloadVersion) | .[]'
9.0.105
9.0.104
```

#### Powershell core
```powershell
> dotnet workload search version --format json --take 2 | ConvertFrom-Json | ForEach-Object { Write-Host $_.workloadVersion }
9.0.105
9.0.104
```
@marcpopMSFT
Copy link
Member

Per conversation earlier today, we agreed to the package@version syntax and we'll start with just the workload and matching manifest. We decided to just use the existing --version or workloadVersion in the global.json for this and look for the @ symbol.

We have three options for fetching this from nuget:

  1. Download all of the available workload sets for the current SDK band and pick the highest that matches
  2. Use the NuGet package tag to start this information and use the api to query the tags
  3. Get NuGet to add a property bag queryable from the API

We agreed to proceed with one since the number of workload sets should be relatively

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Area-CLI Area-Workloads cli-ux Issues and PRs that deal with the UX of the CLI (exit codes, log output, verbs/options, and so on) needs design untriaged Request triage from a team member User Story A single user-facing feature. Can be grouped under an epic.
Projects
None yet
Development

No branches or pull requests

5 participants