add support for outputting content in different formats

[jonsequitur]

A useful capability would be a model whereby developers can set the output based on an object rather than explicitly writing text. We could provide a number of ways of representing that output so that the end user can expect consistent behaviors and choose output formats that suit their needs.

Here's an example of how this might work:

 var commandLine = new CommandLineBuilder()
                              .AddOutputFormat(OutputFormats.Json)
                              .AddOutputFormat(OutputFormats.Csv)
                              .AddOutputFormat(OutputFormats.TabDelimited)
                              .AddOutputFormat(OutputFormats.Xml);

The above would also add an option that would be visible in help:

>my.exe -h

Options:
  --format [json|csv|tab-delimited|xml]        Specifies the output format. 

[MarkMichaelis]

I believe the key requirement that prompted me to raise this (and no doubt you all saw as obvious), is that I want to make it trivially simple for developers to add OutputFormat (and input providers for that matter) to their programs. The goal is that people fall in to automatically being able to have output be produced in any number of the "standard" formats they choose.
A key point that @jonsequitur pointed out during our meeting is that display/view formatting (color, font, bold) is different than the serialization (json, xml, .NET Object?) type formatting and I concur.

[amervitz]

Has there been any progress on this, or are there any alternative methods for obtaining the return value of a command so that it can be manually formatted? I have multiple commands I want to be able to execute without having Console.WriteLine statements in them. Unfortunately the InvokeAsync method on commands only returns an integer. I have tried to replicate the InvocationPipeline methods in an effort to capture the task result, but get stuck on

command-line-api/src/System.CommandLine/Invocation/InvocationPipeline.cs

Line 44 in f26d980

var invocations = new List<InvocationMiddleware>(context.Parser.Configuration.Middleware);

because the Middleware property isn't public.

Thanks,

Alan

[jonsequitur]

We do have work in progress on making the middleware more accessible and easier to customize, including giving you more control over the order of execution. That should be ready in the next few days. Did you try CommandLineBuilder.AddMiddleware?

As for return types from command handlers, it's unlikely we would add the ability to return additional types directly, and might actually remove the int and Task<int> variants to reduce the number of overloads. The "return value" should be set on the InvocationContext.InvocationResult, as is done for example here:

command-line-api/src/System.CommandLine/Invocation/InvocationExtensions.cs

Line 175 in f26d980

context.InvocationResult = new ParseDirectiveResult();

Maybe something like this:

context.InvocationResult = new DisplayResult(myObject);

The next question, of how to format the object, likely falls into the System.CommandLine.Rendering area. The view concepts there are a sketch of the direction we're looking in, so that you can express a layout but we'll handle rendering correctly based on the terminal type, output redirection, etc.

[amervitz]

I'm struggling to make a middleware that can access the return value of a command. This is a simple example attempting to do so, I'm not sure if I'm doing it right:

static void Main(string[] args)
{
    var command = new Command("test");
 
    MethodInfo method = typeof(Program).GetMethod(nameof(DoSomething));
    command.ConfigureFromMethod(method);

    var parser = new CommandLineBuilder()
                    .AddCommand(command)
                    .UseMiddleware(async (context, next) => {
                        await next(context);
                        Console.WriteLine($"context.InvocationResult is null? {context.InvocationResult is null}");
                    })
                    .Build();

    parser.InvokeAsync("test");
}

public static async Task<string> DoSomething()
{
    Console.WriteLine("Start DoSomething");
    return "Hello World!";
}

When executing, the InvocationResult is null instead of Hello World!. This is the output I get:

Start DoSomething
context.InvocationResult is null? True

[jonsequitur]

System.CommandLine is not checking the return value of your handler, so this isn't going to work. It seems like an intuitive thing to try though and maybe should be supported.

[amervitz]

I have tried to add the ability to return a value from a handler but am getting a lot of failed tests afterwards. What is the best way to collaborate on this? Should I open a PR?

[jonsequitur]

If you'd like to open a PR it'll make it much easier to discuss the details of what you'd like to accomplish. I think that will be a very useful discussion. Just be aware that returning other types from handlers is a design change that, while probably quite useful, will result in needing to make a number of other decisions about how to format and display the returned object, and System.CommandLine.Rendering is not as mature as System.CommandLine.

[iBicha]

What's the current state of this feature?

[jonsequitur]

It's still something we're discussing but there's no settled design for it.

@KathleenDollard