Habilidade de Desenvolvedor CLI do System.CommandLine

Você está trabalhando em um aplicativo CLI .NET construído com System.CommandLine v2.x.x, com destino a .NET 8 ou posterior ou qualquer implementação .NET Standard 2.0, incluindo .NET Framework 4.6.1 ou posterior e .NET Core 2.0 ou posterior. Siga estas regras e padrões estritamente ao criar ou modificar comandos CLI.

Visão Geral da Arquitetura

<CLI Project>/
├── Program.cs                       # Entry point and command invocation
└── Commands/
    ├── CommandBase.cs               # Base class for all commands
    ├── GlobalOptions.cs             # Defines global options for the CLI
    ├── RootCommand.cs               # Registers top-level commands
    └── <Group>/                     # One folder per command group
        ├── <Group>Command.cs        # Parent command that registers its children
        └── <Group><Verb>Command.cs  # Leaf command with its handler

REGRA 1 — Prefira uma Classe Base de Comando Específica do Projeto

Prefira definir uma CommandBase abstrata específica do projeto que herde de System.CommandLine.Command. Comandos concretos devem herdar desta classe base para que o comportamento e as convenções compartilhados permaneçam centralizados.

internal abstract class CommandBase : Command
{
    protected CommandBase(string name, string? description = null)
        : base(name, description)
    {
    }
}

internal sealed class MyCommand : CommandBase
{
    public MyCommand()
        : base("command-name", "Help text shown in --help")
    {
        this.SetAction(CommandHandler);
    }

    private async Task<int> CommandHandler(
        ParseResult parseResult,
        CancellationToken cancellationToken)
    {
        // implementation
        return 0;
    }
}

Quando o projeto já possui uma classe base de comando, preserve suas convenções estabelecidas. Caso contrário, introduza uma quando os comandos precisarem de comportamento compartilhado; aplicações simples podem herdar diretamente de Command quando uma classe base não agrega valor significativo.

REGRA 2 — Opções e Argumentos

Definindo Opções

private readonly Option<string> _myOption;

// In constructor:
_myOption = new Option<string>("--my-option")
{
    Description = "Clear description of what this option does",
    Required = true,   // or false
};
_myOption.Aliases.Add("-m");       // Add a short alias
this.Options.Add(_myOption);

Definindo Argumentos (posicionais)

private readonly Argument<string> _fileArgument;

// In constructor:
_fileArgument = new Argument<string>("file")
{
    Description = "Path to the input file"
};
this.Arguments.Add(_fileArgument);

Lendo Valores em Handlers

// Required option/argument — use GetValue:
var value = parseResult.GetValue(_myOption);

REGRA 3 — Padrão de Handler de Comando

Handlers são métodos async conectados via SetAction:

this.SetAction(CommandHandler);

private async Task<int> CommandHandler(ParseResult parseResult, CancellationToken cancellationToken)
{
    // 1. Read option/argument values
    // 2. Load session settings (if needed)
    // 3. Validate configuration early — fail fast with clear error
    // 4. Execute business logic
    // 5. Output results with Console

    return 0; // or non-zero exit code
}

REGRA 4 — Grupo de Comandos (Pai com Subcomandos)

Um comando de grupo registra filhos, mas não chama SetAction:

internal class MyGroupCommand : CommandBase
{
    public MyGroupCommand()
        : base("mygroup", "Manages my-group resources")
    {
        this.Subcommands.Add(new MyGroupListCommand());
        this.Subcommands.Add(new MyGroupCreateCommand());
        this.Subcommands.Add(new MyGroupDeleteCommand());
    }
}

Um comando pode definir tanto uma ação quanto subcomandos quando a invocação direta tiver um comportamento significativo.

REGRA 5 — Registro

• Comandos de nível superior → registre em RootCommand.cs:

  this.Subcommands.Add(new MyGroupCommand());
  

• Subcomandos → registre dentro do construtor do comando pai:

  this.Subcommands.Add(new MyGroupCreateCommand());
  

REGRA 6 — Confirmação do Usuário para Operações Destrutivas

Console.WriteLine("Are you sure you want to delete X? This action cannot be undone. (yes/no)");
var confirmation = Console.ReadLine();
if (confirmation?.ToLower() != "yes" && confirmation?.ToLower() != "y")
{
    Console.WriteLine("Operation cancelled.");
    return 0;
}

…