Albatross.CommandLine 8.0.1-114.main

Albatross.CommandLine

A .NET library that simplifies creating command-line applications with System.CommandLine. It provides automatic code generation and dependency injection support while maintaining full access to System.CommandLine's capabilities. It is opionionated toward async actions with out of box support for action cancellation and graceful shutdown.

🎉 Now using System.CommandLine v2 stable release for improved reliability and long-term support.

✨ Key Features

• 🚀 Minimal Boilerplate - Attribute-based command definition with automatic code generation
• 🔧 Type Safety - Leverages C# nullable reference\value types for automatic requirement detection
• 📦 Dependency Injection - Built-in DI container integration
• 🎯 Full Flexibility - Direct access to System.CommandLine when needed
• 🛠️ Out of Box Support for Cancellation and Graceful Shutdown - Built-in Support for Ctr->C Interruption via Cancellation tokens and Graceful Shutdown
• 🌟 Minimum Dependencies - Only depends on System.CommandLine and Microsoft.Extensions.Hosting.
• 🌟 Easy Extensions Use CommandHost.ConfigureHost to bootstrap additional services or use Albatross.CommandLine.Default to include Serilog logging via Albatross.Logging and Json\Environmental Configuration Support via Albatross.Config.

📖 Documentation

📚 Complete Documentation

Quick Links

• Quick Start Guide - Verb, Option, and Argument attributes
• Code Generator - How automatic code generation works
• Commands Customization - Customize generated Command using partial class

🔧 Dependencies

• System.CommandLine 2.0.1+
• Microsoft.Extensions.Hosting 8.0.1+

🔧 Prerequisites

• C# Compiler 4.10.0+ (included with .NET 8 SDK)

🚀 Quick Start

1. Install Package

<PackageReference Include="Albatross.CommandLine" Version="8.0.1" />

2. Create Program.cs

internal class Program {
		static async Task<int> Main(string[] args) {
			await using var host = new CommandHost("Sample Command Line Application")
				.RegisterServices(RegisterServices)
				// this method is generated by source generator
				.AddCommands()
				.Parse(args)
				.Build();
			return await host.InvokeAsync();
		}
		static void RegisterServices(ParseResult result, IConfiguration configuration, IServiceCollection services) {
			// RegisterCommands method is generated by codegen
			services.RegisterCommands();
			// register your dependencies here
			services.AddSingleton<IMyService, MyService>();
		}
	}
}

3. Define Your Command

[Verb<HelloCommandHandler>("hello", Description = "Say hello to someone")]
public record class HelloOptions {
    // Required argument (position 0)
    [Argument(Description = "Name to greet")]
    public required string Name { get; init; }
    
    // Optional option
    [Option(Description = "Number of times to greet")]
    public int Count { get; init; } = 1;
}

public class HelloCommandHandler : CommandHandler<HelloOptions> {
    public HelloCommandHandler(HelloOptions options) : base(options) {
    }

    public override async Task<int> Invoke(CancellationToken cancellationToken) {
        for (int i = 0; i < options.Count; i++) {
            await this.Writer.WriteLineAsync($"Hello, {options.Name}!");
        }
        return 0;
    }
}

5. Run It!

dotnet run -- hello "World" --count 3

That's it! The code generator automatically creates the command class and service registrations.

🌟 Advanced Features

Sub-Commands

[Verb<DatabaseBackupAction>("database backup")]
[Verb<DatabaseRestoreAction>("database restore")]
// Creates: database backup, database restore

Shared Options

[Verb<ProjectCommandHandler>("project build", UseBaseParamsClass = typeof(ProjectOptions))]
public record class BuildOptions : ProjectOptions {
    [Option] public string Configuration { get; init; } = "Release";
}

Manual Commands

// Full System.CommandLine control when needed
setup.CommandBuilder.AddWithParentKey("tools", new CustomCommand());

🎯 Global Options

The library creates a single recursive option for logging purposes.

• -v, --verbosity - Logging level (Error, Warning, Information, Info, Debug, Trace)

🤝 Samples

See the Sample.CommandLine project for comprehensive examples of all features.

📦 Related Packages

• Albatross.CommandLine.Default - Default setup with logging and configuration

📖 Read the Full Documentation →