ConsoleAppFramework

ConsoleAppFramework uses several strategies to convert string arguments into C# types:

• Primitives: Uses TryParse for string, char, sbyte, byte, short, int, long, uint, ushort, ulong, decimal, float, and double.
• ISpanParsable<T>: For types implementing ISpanParsable<T> (e.g., DateTime, Guid, BigInteger), it uses the standard TryParse methods.
• Enums: Parsed using Enum.TryParse(ignoreCase: true).
• Booleans: Treated as flags. They are always optional and become true if the parameter name is present in the arguments.
• Arrays (T[]):
  • If the value starts with [, it is parsed via JsonSerializer.Deserialize.
  • Otherwise, it is parsed as comma-separated values (e.g., 1,2,3 or [1,2,3]).
  • Use [] for an empty array.
• Params (params T[]): All subsequent arguments are captured into the array.
• Objects: If no other pattern matches, JsonSerializer.Deserialize<T> is used.
  • Note: CancellationToken, ConsoleAppContext, and parameters marked with [FromServices] are excluded from JSON binding.
  • You can customize deserialization by setting ConsoleApp.JsonSerializerOptions.

Filters allow you to hook into the execution pipeline before and after a command runs. To create a filter, define an internal class that implements ConsoleAppFilter and overrides InvokeAsync.

Filter Lifecycle:

1. Call await Next.InvokeAsync(context, cancellationToken) to proceed to the next filter or the command body.
2. Use try/catch/finally blocks within InvokeAsync to handle logic around the command execution.

Attachment Levels: Filters can be attached at three levels. The execution order is global $\rightarrow$ class $\rightarrow$ method.

• Global: Use app.UseFilter<T>() on the builder.
• Class: Use [ConsoleAppFilter<T>] on the command class.
• Method: Use [ConsoleAppFilter<T>] on the specific command method.

// 1. Define the filter
internal class NopFilter(ConsoleAppFilter next) : ConsoleAppFilter(next)
{
    public override async Task InvokeAsync(ConsoleAppContext context, CancellationToken cancellationToken)
    {
        try
        {
            /* on before */
            await Next.InvokeAsync(context, cancellationToken);
            /* on after */
        }
        catch
        {
            /* on error */
            throw;
        }
        finally
        {
            /* on finally */
        }
    }
}

// 2. Attach filters
var app = ConsoleApp.Create();

// Global
app.UseFilter<NopFilter>(); 

app.Add<MyCommand>();
app.Run(args);

[ConsoleAppFilter<NopFilter>] // Per class
public class MyCommand
{
    [ConsoleAppFilter<NopFilter>] // Per method
    public void Echo(string msg) => Console.WriteLine(msg);
}

ConsoleAppFramework supports OpenTelemetry natively if you configure OpenTelemetry settings using Host.CreateApplicationBuilder() before converting it with .ToConsoleAppBuilder(). This allows you to capture traces, metrics, and logs from your commands, including instrumentation for HTTP clients and runtime metrics.

builder.Services.AddOpenTelemetry()
    .UseOtlpExporter()
    .ConfigureResource(resource =>
    {
        resource.AddService("ConsoleAppFramework Telemetry Sample");
    })
    .WithMetrics(metrics =>
    {
        metrics.AddRuntimeInstrumentation()
            .AddHttpClientInstrumentation();
    })
    .WithTracing(tracing =>
    {
        tracing.SetSampler(new AlwaysOnSampler())
            .AddHttpClientInstrumentation()
            .AddSource(ConsoleAppFrameworkSampleActivitySource.Name);
    })
    .WithLogging(logging =>
    {
        // configure for logging
    });

var app = builder.ToConsoleAppBuilder();

app.Add<SampleCommand>();

// setup filter
app.UseFilter<CommandTracingFilter>();

await app.RunAsync(args);

You can bind JSON configuration files to strongly-typed options using Microsoft.Extensions.Configuration.Json and Microsoft.Extensions.Options.ConfigurationExtensions.

1. Call .ConfigureDefaultConfiguration() to automatically set the base path to the current directory and add appsettings.json (optional).
2. Use .ConfigureServices to bind sections of the configuration to your option classes using services.Configure<TOptions>(configuration.GetSection("SectionName")).
3. Inject IOptions<TOptions> into your command classes via the constructor.

// appsettings.json
{
  "Position": {
    "Title": "Editor",
    "Name": "Joe Smith"
  }
}

// Program.cs
var app = ConsoleApp.Create()
    .ConfigureDefaultConfiguration()
    .ConfigureServices((configuration, services) =>
    {
        services.Configure<PositionOptions>(configuration.GetSection("Position"));
    });

app.Add<MyCommand>();
app.Run(args);

public class MyCommand(IOptions<PositionOptions> options)
{
    public void Echo() => Console.WriteLine($"{options.Value.Title}");
}

public class PositionOptions
{
    public string Title { get; set; } = "";
    public string Name { get; set; } = "";
}