dotnet / dotnet/command-line-api
Customize version style
- Dominant language
- C#
- Stars
- 3.7k
- Forks
- 428
- PR merge metrics
- No merged PRs in 30d
Description
With the upcoming new standardization of `name@version` style in SDK https://github.com/dotnet/sdk/issues/47980, these type of differences will be observed by the user in .NET 10:
```diff
# dotnet tool install
- dotnet tool install --global dotnet-ef --version 10.0.0-preview.3.25171.6
+ dotnet tool install --global dotnet-ef@10.0.0-preview.3.25171.6
# dotnet new template
- dotnet new install BenchmarkDotNet.Templates::0.14.0
+ dotnet new install BenchmarkDotNet.Templates@0.14.0
# dotnet package add
- dotnet package add Newtonsoft.Json --version 13.0.3 --project .
+ dotnet package add Newtonsoft.Json@13.0.3 --project .
```
Currently, there is no idiomatic way to customize the usage line in command help. The workaround is to iterate over help section, skip the first line and overwrite it https://github.com/dotnet/sdk/pull/47961#issuecomment-2761872856, which is quite fragile as it can break if position of Usage is moved from index 1.
#### Proposal
One of these options may fit the current design:
1. Add a general purpose API to customize any predefined help section:
```c#
public enum HelpSection { Description, Usage, Arguments }
public class HelpBuilder
{
public void CustomizeSection(HelpSection section, Func>> sectionProducer);
}
// builder.CustomizeUsage(HelpSection.Usage, ctx => _ => { Console.WriteLine("dotnet tool install dotnet-ef[@version]"); return true; });
```
2. Add an API to customize the usage line:
```c#
public class HelpBuilder
{
public void CustomizeUsage(Func usageProducer);
}
// builder.CustomizeUsage(ctx => "dotnet tool install dotnet-ef[@version]");
```
3. Add an API explicitly for version style in usage:
```c#
public class HelpBuilder
{
public void CustomizeUsageVersion(string joiner, bool optional);
}
// builder.CustomizeUsageVersion("@" /* or :: etc. */, false); // name@version
// builder.CustomizeUsageVersion("@" /* or :: etc. */, true); // name[@version]
```
Contributor guide
Assessment
This issue has not been assessed yet.