Albatross.CommandLine 7.5.6

Albatross.CommandLine

An integration library that provdes dependency injection, configuration and logging support for System.CommandLine library. It uses Albatross.CommandLine.CodeGen to generate commands and options automatically while giving developers the flexibility to customize and leverage the capability of System.CommandLine library.

Features

• Dependency Injection enabled by Code Generator.
• Logging integration with Serilog provided by Albatross.Logging.
• Easy configuration setup provided by Albatross.Config.

Related Articles

• Code Generator
• Conventions
• Global options
• Command Options
• Error Handling

Quick Start (Sample Program)

• Create a .net8 Console program
  • Make sure the <Nullable>enable</Nullable> option is enabled for the project.
• Reference Albatross.CommandLine from nuget. Albatross.CommandLine.CodeGen should be referenced automatically as a dev dependency.
• Create a class MySetup.cs that inherits base class Albatross.CommandLine.Setup

    public class MySetup : Setup{
    	protected override string RootCommandDescription => "Put Your Root Command Description Here";
    	public override void RegisterServices(InvocationContext context, IConfiguration configuration, EnvironmentSetting envSetting, IServiceCollection services) {
    		base.RegisterServices(context, configuration, envSetting, services);
    		// RegisterCommands method is generated by codegen
    		services.RegisterCommands();
    		// register your services here.
    		services.AddMyProxy();
    	}
    }
  

• Update the program.cs file

    internal class Program {
    	static Task<int> Main(string[] args) =>
    		new MySetup()
    			.AddCommands()	// this method is generated by CodeGen
    			.CommandBuilder
    			.Build()
    			.InvokeAsync(args);
    }
  

• Create a new class file MyCommandHandler.cs with the following code:

    [Verb("my-command", typeof(MyCommandHandler), Description = "My Test Command")]
    public record class MyCommandOptions {
    	public string Name { get; set; } = string.Empty;
    }
    public class MyCommandHandler : ICommandHandler {
    	private readonly ILogger logger;
    	private readonly MyCommandOptions options;
  
    	public MyCommandHandler(ILogger logger, IOptions<MyCommandOptions> options) {
    		this.logger = logger;
    		this.options = options.Value;
    	}
    	// this method is not used by System.CommandLine
    	public int Invoke(InvocationContext context) => throw new System.NotSupportedException();
    	public Task<int> InvokeAsync(InvocationContext context) {
    		logger.LogInformation("Command {name }is invoked with parameter of {param}", context.ParsedCommandName(), options.Name);
    		return Task.FromResult(0);
    	}
    }
  

• When the code above is saved, code generator will generate the code below automatically

    // MyCommand
    using System;
    using System.CommandLine;
    using System.IO;
    using System.Threading.Tasks;
  
    #nullable enable
    namespace Sample.CommandLine
    {
    	public sealed partial class MyCommand : Command
    	{
    		public MyCommand() : base("my-command", null)
    		{
    			this.Option_Name = new Option<string>("--name", null)
    			{
    				IsRequired = true
    			};
    			this.AddOption(Option_Name);
    		}
  
    		public Option<string> Option_Name { get; }
    	}
    	public static class RegistrationExtensions
    	{
    		public static IServiceCollection RegisterCommands(this IServiceCollection services)
    		{
    			services.AddKeyedScoped<ICommandHandler, Sample.CommandLine.MyCommandHandler>("my-command");
    			services.AddOptions<MyCommandOptions>().BindCommandLine();
    			return services;
    		}
    	}
    	public static Setup AddCommands(this Setup setup)
    	{
    		setup.AddCommand<MyCommand>();
    		return setup;
    	}
    }
    #nullable disable
  

• We now have a functional command line program completed with dependency injection, logging and config setup.

Global Options

This global option class is defined as below. Its functionalities are baked into the parent command handler and available for all commands.

public record class GlobalOptions {
	// default is Error
	public LogLevel? Verbosity { get; set; }
	// when true, log the duration of command execution in milliseconds
	public bool Benchmark { get; set; }
	// when true, show the full stack when there is an exception
	public bool ShowStack { get; set; }
}

Error Handling

• Unhandled command handler exception will be caught and an error code of 10000 will be returned. The exception message will be logged as error. If the show-stack option is set, the full code stack will be logged instead.
• An error code of 9999 will be returned if there is an issue constructing the command handler instance. It could happen when the dependency is not property configured.
• An error code of 9998 will be returned if the command handler is not registered. This could happen if the CodeGenExtensions.RegisterCommands() method is not used.
• If none of the defined commands shows up, CodeGenExtensions.AddCommands() method is not invoked.