Naming mismatch between options/arguments and handler parameters is non-obvious

[jonsequitur]

System.CommandLine's most common usability issue is that handler parameters whose name doesn't match an option or argument will never be successfully bound at invocation time.

For example, it may seem intuitive that the following should work, but handler parameter i will never be bound:

var command = new RootCommand
{ 
    new Option<int>("--an-int")
};

command.Handler = CommandHandler.Create<int>( i => /*   */ );

The alternative APIs were introduced here:

• CommandHandler.Create without name matching #1012

A more flexible approach (using a similar API pattern but generating the handlers using source generators) is being worked out here:

• Source generators for command handlers #1362

Possible approaches include:

• Add an ordering-based matching strategy. This possibly suffers from other non-obviousness problems. Maybe the two strategies can operate together.
• Add an error checking mechanism. Ideally this would not be a runtime check since, once compiled, it would be a continual performance hit while the answer would never change. An analyzer might be a good approach.

[jonsequitur]

Potential solution: #1012

[tibel]

What about complex model binding?

This is something I'm using currently mostly because I have to many arguments/options.

Also I like to have this CommandOptions class:

• the command handler method has fewer parameters
• it looks familiar to ASP.NET Core options pattern

[jonsequitur]

It's a problem to be solved and is part of why #1012 hasn't been merged. Proposals are welcome.

[tibel]

Currently I create the handler like this:

rootCommand.Handler = CommandHandler.Create(
  (IConsole console, CancellationToken cancellationToken, CommandArguments arguments) => 
    Handle(console, cancellationToken, arguments));

Maybe you can add something like CommandHandler.CreateForModel<TModel>(...) that uses name-based matching of options/arguments to their corresponding model properties.

[jonsequitur]

See #1362 for the direction we're leaning for a fuller solution to this issue.

[cwellsx]

Other ideas,

1. If it's unambiguous then don't require a name match -- an example of when it's unambiguous includes, when there is only one parameter; another example might be, when there's only parameter of each given type
2. When it is ambiguous:
   • Keep the current name-matching using reflection (because it's a compact notation to write)
   • Decorate the parameters with a type of attribute which specifies the binding (because using an attribute might be idiomatic; and it doesn't change the signature, so it doesn't have the difficulties in your first solution e.g. overloads for complex types and IConsole)
   • Better error reporting -- my experience with a failure-to-bind was that a command-line argument was discarded and null was passed as the parameter value; perhaps failure-to-bind should throw an informative custom exception which would lead the developer to the fix.

Perhaps "failure to bind" is always unexpected, indicating a programmer error, therefore worthy of an exception -- and not the same as a "failure to parse", e.g. an unexpected option or argument value entered by the user.

[jonsequitur]

Perhaps "failure to bind" is always unexpected, indicating a programmer error, therefore worthy of an exception -- and not the same as a "failure to parse", e.g. an unexpected option or argument value entered by the user.

I think that failure to bind is always a programmer error. We don't want to have that be a runtime error that the end user sees, nor do we want to incur runtime cost validating it. It ideally needs to be correct at compile time, which is why we're looking to move away from the name-based convention as the default.