dotnet / dotnet/command-line-api

Customize version style

Open
#2,542 3 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.