DotMake.CommandLine

DotMake automatically populates properties of your command classes based on command-line input. The framework determines if an option or argument is required or optional based on the following rules:

Required

An option/argument is required if:

• It is a reference type (e.g., string) with no property initializer.
• It is a nullable value type (e.g., bool?) with no property initializer.
• It is initialized with null or null! (e.g., public string Arg { get; set; } = null!;).
• It is explicitly marked via the Required = true property in the [CliArgument] or [CliOption] attribute.
• It uses the C# required modifier (e.g., public required string Opt { get; set; }).

Optional

An option/argument is optional if:

• It is a value type (e.g., bool, int, enum) with no property initializer, as these have non-null default values.
• It has a non-null property initializer (e.g., public string Arg { get; set; } = "Default";).
• It is explicitly marked via [CliArgument(Required = false)] or [CliOption(Required = false)].

Note: When using Required = false for reference types, you should check for null in your Run method to determine if the user omitted the option.

public string Opt1 { get; set; } // => Required because default value is null

[CliOption]
public bool Opt2 { get; set; } // => Optional because default value is non-null

[CliOption]
public bool? Opt3 { get; set; } // => Required because default value is null

[CliOption(Required = false)]
public string Opt1 { get; set; } // => Optional because attribute has `Required = false`

The delegate-based model is ideal for simple applications. Instead of a class, you pass a lambda expression or a method reference directly to Cli.Run or Cli.RunAsync.

Rules for Delegates:

• Parameters in the delegate represent CLI options or arguments.
• By default, a parameter is treated as a CLI option. Use [CliArgument] to change it to an argument.
• You can use attributes like [CliOption] or [CliCommand] on the delegate itself (requires <LangVersion>10.0</LangVersion> if target framework is below .NET 6.0).
• Set default values for parameters to make them optional.
• Delegates can be async and return void, int, Task, or Task<int>.

using System;
using DotMake.CommandLine;

Cli.Run(([CliArgument]string arg1, bool opt1) =>
{
    Console.WriteLine($"Value for {nameof(arg1)} parameter is '{arg1}'");
    Console.WriteLine($"Value for {nameof(opt1)} parameter is '{opt1}'");
});

The class-based model is recommended for complex applications requiring sub-commands or command inheritance.

In this model, you define a class representing your command. DotMake.CommandLine uses source generators to turn your class and its properties into CLI commands, options, and arguments at compile time. At runtime, it parses the arguments and binds them to your class properties.

Key Workflow:

1. Mark the command class with [CliCommand].
2. Define properties for arguments using [CliArgument] and options using [CliOption].
3. Implement a handler method named Run or RunAsync.
4. Execute the application using Cli.Run<T>(args) or Cli.RunAsync<T>(args).

using System;
using DotMake.CommandLine;

// Run your CLI app:
Cli.Run<RootCliCommand>(args);

// Define your root command:
[CliCommand(Description = "A root cli command")]
public class RootCliCommand
{
    [CliArgument(Description = "Description for Argument1")]
    public string Argument1 { get; set; } = "DefaultForArgument1";

    [CliOption(Description = "Description for Option1")]
    public bool Option1 { get; set; };
 
    public void Run()
    {
        Console.WriteLine($"Value for {nameof(Argument1)} property is '{Argument1}'");
        Console.WriteLine($"Value for {nameof(Option1)} property is '{Option1}'");
    }
}

To avoid repeating common options and arguments across multiple commands, you can use C# class inheritance or interfaces.

• Class Inheritance: Define common options in an abstract base class. Derived command classes will inherit these options and their command handlers (Run or RunAsync).
• Interface Implementation: Use interfaces to group sets of options. Since C# supports multiple interface implementation, you can compose a command from several different option groups.

Overriding Behavior: If a derived class provides its own property attribute or property initializer for a member inherited from a base class or interface, the derived class's version (the attribute and the default value) will be used by the CLI.

[CliCommand]
public class InheritanceCliCommand : CredentialCommandBase, IDepartmentCommand
{
    public string Department { get; set; } = "Accounting";
}

public abstract class CredentialCommandBase
{
    [CliOption(Description = "Username of the identity performing the command")]
    public string Username { get; set; } = "admin";

    [CliOption(Description = "Password of the identity performing the command")]
    public string Password { get; set; }

    public void Run()
    {
        Console.WriteLine($"I am {Username}");
    }
}

public interface IDepartmentCommand
{
    [CliOption(Description = "Department of the identity performing the command (interface)")]
    string Department { get; set; }
}

To enforce that a user provides exactly one option from a specific set, use the RequiredGroups property on the [CliCommand] attribute.

1. Assign a common Group name to the related options using [CliOption(Group = "...")].
2. Add that group name to the RequiredGroups array in the [CliCommand] attribute.

If no option from the required group is provided, the CLI will display an error.

[CliCommand(RequiredGroups = new[] { "auth" })]
public class ReportCommand
{
    // Mutually exclusive group (not required, but only one allowed)
    [CliOption(Group = "output-format")]
    public bool Json { get; set; }

    [CliOption(Group = "output-format")]
    public bool Xml { get; set; }

    // Required group (exactly one must be provided)
    [CliOption(Group = "auth")]
    public string ApiKey { get; set; }

    [CliOption(Group = "auth")]
    public string Token { get; set; }
    
    public void Run(CliContext context)
    {
        context.ShowValues();
    }
}