Tagging subscribers to this area: @dotnet/area-system-runtime

@nobledog This sounds like a product issue, not a docs issue. Is that correct?

Hmm, let me give you some background and can decide whether its a doc or product issue.

Apologies if this is longer winded than you would want or can even conceive of. I am not sure how much input you expect and/or whether you might be one of CommandLine's coders or engineers who might want more details.

Subsequent to sending in the comment you are responding to, I found another place in the online docs that explained an alternative approach to implementing handlers that require many arguments. It involves using a SetHandler method that has the signature shown below (taken from Handler.Func.cs around line 26):

/// <summary>
/// Sets a command's handler based on a <see cref="Func{Task,InvocationContext}"/>.
/// </summary>
public static void SetHandler( this Command command,   Func<InvocationContext, Task> handle) =>
    command.Handler = new AnonymousCommandHandler(handle);

The nearest method to this in the current documentation looks like:

 SetHandler<T>(Command, Func<T,Task>, IValueDescriptor[])

Indeed it defined directly below the ither one in the source file.

Presumably, in code elsewhere in the CommandLine package that I haven't bothered to track down the Command class knows how to pass an InvocationContext to this type of delegate instead of a whole bunch of generically parameterized arguments. The InvocationContext allows one to reach any Options or Arguments defined on the Command object using a linkage from the InvocationContext to its ParseResult and to that object's GetValueForOption(Option) method.

While it is nice to have some of the other overloads for passing Options/Arguments directly to the handler, the doc presently lists variants supporting as many as 16 of them. However, only around 8 are actually implemented in Handler.Func.cs. This is what led to my initial report. I was still trying to figure out a good workaround. I realize CommandLine is still pre-release so I am not complaining. But I am sure you will want the doc issue cleaned up prior to release.

I am guessing that maybe the implementers decided that having such a bevy of overloads was silly past 8 and added the alternate
approach with the InvocationContext to avoid the proliferation. Fact is, it's a much better solution as far as I am concerned.

Other than there being those missing overloads all the code seems to work perfectly find and, to reiterate, I think, the added method was sound design.

I stumbled upon the InvocationContext approach on the learn.microsoft.com site. The relevant page is:

   https://learn.microsoft.com/en-us/dotnet/standard/commandline/model-binding

The section is called "How to bind arguments to handlers in System.CommandLine". It describes the InvocationContext approach and it also correctly remarks on the more limited set of overloads that actually exist. So, I think it's mostly a question of updating the doc at 'https://learn.microsoft.com/en-us/dotnet/api/system.commandline.handler.sethandler'. Seems more a doc issue after all.

For what it is worth, please tell the implementers I think they did excellent work. I am not using it in any extremely intensive way but it has worked well and, except for my one little problem long since solved, has proven easy to use and more than sufficiently capable. I was not needing some kind of getop, after all though I suppose it could grow into something hoary and venerable like that.

Let me know if you need any more information. Regards, CM