How can I customise help for an option within a command?

[ashscodes]

I was reading the release for the notes about Customizing help for a single option or argument and all the examples use an instance of the CommandLineBuilder. Is it possible to customise the help when declaring a new Option or in the constructor for a class. At the moment the project I am developing basically looks like this:

// Commands are added as a Singleton to IServiceCollection and then added to the root command.
internal static Parser Build(ServiceProvider serviceProvider)
{
    RootCommand rootCommand = new RootCommand(description: "Repository management tool.");
    foreach (Command command in serviceProvider.GetServices<Command>())
    {
        rootCommand.AddCommand(command);
    }

    // Program.cs invokes the result of this async with the args.
    return new CommandLineBuilder(rootCommand).UseDefaults().Build();
}

public class ConfigCommand : Command
{
    private readonly string[] Force = new string[] { "-f", "--force" };

    private readonly string[] Generate = new string[] { "-g", "--generate" };

    public ConfigCommand() : base(
        name: "config",
        description: "Options for creating, getting or setting app configuration.")
    {
        Option forceOption = new Option<bool>(
                aliases: this.Force,
                description: "Specifies that an existing config file should be overwritten.");

        Option generateOption = new Option<bool>(
                aliases: this.Generate,
                description: "Creates a new config file in the current directory.");

        this.AddOption(generateOption);
        this.AddOption(forceOption);

        this.SetHandler(
            (bool generate, bool force) =>
            {
                ConfigHandler.Invoke(generate, force);
            },
            generateOption,
            forceOption);
    }
}

Unless I am missing something, this is not currently possible unless the CommandLineBuilder is used, and I assume I shouldn't be using that for anything other than a single command which includes any subcommands, in this case the RootCommand. It would be cool to be able to apply a customisation object directly to the option constructor.

I have seen the example in the tests here, but this I do not think I can apply it to an unknown number of commands being passed via the ServiceProvider.

Apologies if anything is unclear, there's a learning curve involved for me here that extends outside of System.CommandLine :)

[jonsequitur]

Configuration of things that cut across the entire parser and potentially affect all commands, options, and arguments are configurable via CommandLineConfiguration. Its constructor is a bit involved, especially regarding composing the middleware pipeline, so CommandLineBuilder exists to make it more composable.

HelpBuilder is an interesting case because some of its functionality is specific to a symbol but some (like the layout) cuts across all of them. It also needs access to other pieces of the configuration such as other commands for hierarchical context and LocalizationResources.

One approach that can work for keeping richer help customization code close to the relevant symbols is to inherit Command, Option, or Argument as needed and then use the HelpBuilder customization APIs to make use of that. It doesn't avoid using CommandLineBuilder at this point but it does offer some flexibility in how you organize some of the help code.

[ashscodes]

Thanks for the quick response. I'm not sure I fully understand, does this mean I would have to introduce CommandLineBuilder in to the constructor of every subcommand too? How would that work if the only instance I currently create of it adds the RootCommand where it builds and returns the Parser? The aim was just to use HelpBuilder.CustomizeSymbol() to available options in the column text as in the release notes.

[jonsequitur]

No, the commands and options won't have to have a reference to the CommandLineBuilder. But currently the only way to customize the help for a specific Option is to use HelpBuilder.CustomizeSymbol, which you can get to through CommandLineBuider.UseHelp or UseHelpBuilder.

[ashscodes]

Thanks. I'm going to leave the customisation then. I guess I could add some kind of interface/method on an inherited Option and loop through the sub commands and their options in the CommandLineBuilder created with the root command, but it doesn't really seem worth it at the moment.

For what it's worth, I really like the library and have enjoyed getting to know more about it through the alpha and beta stages. Looking forward to seeing where it goes in the future. Thanks.

[ansible42]

I like this way of building up commands, what is a good way to add optional parameters to the SetHandler? I keep getting command not found blah blah blah warnings.

[jonsequitur]

@ansible42 Could you share some example code?

[ansible42]

Quick example of what I was looking to do. Just looking at how to do an optional command, if count is not found use the default value for the optional arguments.

class StopIt : Command
{
    private readonly string[] count = new string[] { "--count", "-c" };
    public StopIt() : base(
        name: "stopit",
        description: "Make them stop ")
    {
        Option count = new Option<int>(
            aliases: this.count,
            description: "how many time do I have to tell you ",    
            getDefaultValue: ()=> 1
            ){ IsRequired = false};
        ;
        this.SetHandler(
            (int num) =>
            {
                for (int i = 0; i < num; i++)
                {
                    Console.WriteLine("Stop it!!");
                    Console.WriteLine("But I am not touching you.");
                }
            },
            count
            );
    }
}

[jonsequitur]

Ah, I see. You need to add the option to the command in addition to passing it to SetHandler. Try this:

using System.CommandLine;

class StopIt : Command
{
    private readonly string[] count = new string[] { "--count", "-c" };
    public StopIt() : base(
        name: "stopit",
        description: "Make them stop ")
    {
        Option count = new Option<int>(
            aliases: this.count,
            description: "how many time do I have to tell you ",    
            getDefaultValue: ()=> 1);
        
        AddOption(count);

        this.SetHandler(
            (int num) =>
            {
                for (int i = 0; i < num; i++)
                {
                    Console.WriteLine("Stop it!!");
                    Console.WriteLine("But I am not touching you.");
                }
            },
            count
            );
    }
}

new StopIt().Invoke("");