ApplicationBuilderHelpers

A .NET library for building command-line applications with a fluent API, dependency injection, and modular architecture.

• Targets: net6.0–net10.0 · AOT-compatible · Trimmable
• Dependencies: Microsoft.Extensions.Hosting, Microsoft.Extensions.DependencyInjection.Abstractions, AbsolutePathHelpers

• 🎯 Command-based Architecture — Command patterns with automatic argument parsing
• 🔧 Fluent Builder API — Intuitive setup via method chaining
• 💉 Dependency Injection — Full Microsoft.Extensions.DependencyInjection support
• 🏗️ Modular Application Structure — Reusable ApplicationDependency modules with lifecycle hooks
• ⚙️ Configuration — .NET configuration integration with @ref: reference values
• 🎨 Attributes — [Command], [CommandOption], [CommandArgument] for declarative CLI definitions
• 🎯 Sub-Commands — Hierarchical commands via space-separated names
• 🖌️ Themable Help — 5 built-in console color themes, configurable help width
• 🧩 Multiple Host Types — HostApplicationBuilder, WebApplicationBuilder, custom builders

dotnet add package ApplicationBuilderHelpers

// Program.cs
using ApplicationBuilderHelpers;

return await ApplicationBuilder.Create()
    .AddApplication<CoreApplication>()
    .AddCommand<GreetCommand>()
    .RunAsync(args);

[Command(description: "Greet someone")]
public class GreetCommand : Command
{
    [CommandArgument(Name = "name", Position = 0, Description = "Who to greet")]
    public string Name { get; set; } = "World";

    protected override ValueTask Run(ApplicationHost<HostApplicationBuilder> applicationHost, CancellationToken cancellationToken)
    {
        Console.WriteLine($"Hello, {Name}!");
        return ValueTask.CompletedTask;
    }
}

$ myapp Alice
Hello, Alice!

Extend Command and override Run. Define options with [CommandOption] and positional arguments with [CommandArgument]. Commands can register their own services, middleware, and configuration — they inherit the full ApplicationDependency lifecycle.

[Command("build", description: "Build the project")]
public class BuildCommand : Command
{
    [CommandOption('v', "verbose", Description = "Enable verbose output")]
    public bool Verbose { get; set; }

    protected override async ValueTask Run(ApplicationHost<HostApplicationBuilder> applicationHost, CancellationToken cancellationToken)
    {
        // ...build logic...
    }
}

Group shared services and configuration into reusable modules:

public class CoreApplication : ApplicationDependency
{
    public override void AddServices(ApplicationHostBuilder appBuilder, IServiceCollection services)
    {
        services.AddSingleton<IMyService, MyService>();
    }
}

See Application Dependencies for the full lifecycle reference.

Use space-separated names for hierarchical commands. Try myapp deploy prod or myapp deploy prod rollback:

[Command("deploy prod", description: "Deploy to production")]
public class DeployProductionCommand : Command { /* ... */ }

RunAsync returns an exit code:

Return normally on success. Throw CommandException for errors to return a non-zero exit code from RunAsync:

throw new CommandException("Operation failed", exitCode: 1);

Shell completion (complete / completions ...) resolves through the CompletionGateway pre-parse stage first — see Commands for the consolidated 0/1/2 exit matrix.

See Advanced Topics for more on sub-commands, custom host types, error handling, and error footers.

┌─────────────────────┐
│  ApplicationBuilder │ ← Entry Point (fluent API)
└──────────┬──────────┘
           │
    ┌──────▼──────┐
    │  Commands   │ ← Command Registration (+ own lifecycle hooks)
    └──────┬──────┘
           │
    ┌──────▼──────────┐
    │  Applications   │ ← Application Modules (lifecycle hooks)
    └──────┬──────────┘
           │
    ┌──────▼───────────┐
    │  Host Builder    │ ← Host Configuration
    └──────┬───────────┘
           │
    ┌──────▼──────┐
    │  Services   │ ← Dependency Injection
    └──────┬──────┘
           │
    ┌──────▼──────────┐
    │  Middleware     │ ← Request Pipeline
    └──────┬──────────┘
           │
    ┌──────▼──────┐
    │  Execution  │ ← Command Execution
    └─────────────┘

RunAsync pipeline stages: hierarchy build → CompletionGateway (completion > help > parse > version) → help → parse → version check → execute.

Contributions are welcome! Please submit a Pull Request.

MIT — see the LICENSE file.