Partilhar via

Conclusão automática por tabulação para System.CommandLine

Os aplicativos que usam System.CommandLine têm suporte interno para conclusão de guias em determinados shells. Para habilitá-lo, o usuário final deve executar algumas etapas uma vez por shell. Feito isso, o preenchimento da guia é automático para valores estáticos em seu aplicativo, como valores de enum ou valores definidos pela chamada AcceptOnlyFromAmong(String[]). Você também pode personalizar o completamento de 'tabs' fornecendo valores dinamicamente durante a execução.

Ativar conclusão automática com tab

Na máquina onde você (o utilizador final) quer ativar a conclusão de separador, siga estes passos.

Para a CLI do .NET:

Para outras aplicações de linha de comandos baseadas em System.CommandLine:

  • Instale a dotnet-suggest ferramenta global:

    dotnet tool install -g dotnet-suggest

  • Adicione o script de shim apropriado ao seu perfil de shell. Talvez seja necessário criar um arquivo de perfil do shell. O script shim encaminha solicitações de conclusão do shell para a ferramenta dotnet-suggest, que as delega ao aplicativo apropriado baseado em System.CommandLine.

    • Para bash, adicione o conteúdo de dotnet-suggest-shim.bash a ~/.bash_profile.

    • Para zsh, adicione o conteúdo de dotnet-suggest-shim.zsh a ~/.zshrc.

    • Para o PowerShell, adiciona o conteúdo do dotnet-suggest-shim.ps1 ao teu perfil PowerShell e depois reinicia o PowerShell. Pode encontrar o caminho esperado para o seu perfil PowerShell com o seguinte comando:

      echo $profile

  • Registre o aplicativo chamando dotnet-suggest register --command-path $executableFilePath, onde $executableFilePath é o caminho para o arquivo executável do aplicativo.

Assim que o shell do utilizador estiver configurado e o executável for registado, as conclusões funcionarão para todas as aplicações criadas usando System.CommandLine.

Para cmd.exe no Windows (o Prompt de Comando do Windows), não existe um mecanismo de conclusão de separador plugável, por isso não está disponível um script 'shim'. Para outros shells, procure um problema no GitHub que esteja rotulado Area-Completions. Se não encontrar um problema, pode abrir um novo.

Obter valores de conclusão de tabulação em tempo de execução

O código a seguir mostra uma aplicação que recupera valores para conclusão de tabulação dinamicamente durante a execução. O código recebe uma lista das datas da semana seguinte à atual. A lista é fornecida à opção --date chamando o CompletionSources.Add.

using System.CommandLine;
using System.CommandLine.Completions;
using System.CommandLine.Parsing;

new DateCommand().Parse(args).Invoke();

class DateCommand : Command
{
    private Argument<string> subjectArgument = new("subject")
    {
        Description = "The subject of the appointment."
    };
    private Option<DateTime> dateOption = new("--date")
    {
        Description = "The day of week to schedule. Should be within one week."
    };

    public DateCommand() : base("schedule", "Makes an appointment for sometime in the next week.")
    {
        this.Arguments.Add(subjectArgument);
        this.Options.Add(dateOption);

        dateOption.CompletionSources.Add(ctx => {
            var today = System.DateTime.Today;
            List<CompletionItem> dates = new();
            foreach (var i in Enumerable.Range(1, 7))
            {
                var date = today.AddDays(i);
                dates.Add(new CompletionItem(
                    label: date.ToShortDateString(),
                    sortText: $"{i:2}"));
            }
            return dates;
        });

        this.SetAction(parseResult =>
        {
            Console.WriteLine($"Scheduled \"{parseResult.GetValue(subjectArgument)}\" for {parseResult.GetValue(dateOption)}");
        });
    }
}

Os valores mostrados quando a tecla Tab é pressionada são fornecidos como CompletionItem exemplos:

dates.Add(new CompletionItem(
    label: date.ToShortDateString(),
    sortText: $"{i:2}"));

As seguintes CompletionItem propriedades são definidas:

  • Label é o valor de conclusão a ser mostrado.
  • SortText garante que os valores na lista são apresentados na ordem correta. É definido convertendo i para uma cadeia de dois dígitos, de modo que a ordenação baseia-se em 01, 02, 03, e assim sucessivamente, até ao 14. Se não definires este parâmetro, a ordenação baseia-se em Label, que neste exemplo está em formato de data curta e não ordena corretamente.

Existem outras CompletionItem propriedades, como Documentation e Detail, mas ainda não são usadas em System.CommandLine.

A lista de completamento de aba dinâmica criada por este código também aparece na saída de ajuda.

Description:
  Makes an appointment for sometime in the next week.

Usage:
  schedule <subject> [options]

Arguments:
  <subject>  The subject of the appointment.

Options:
  --date                                                                          The day of week to schedule. Should be within one week.
  <12/4/2025|12/5/2025|12/6/2025|12/7/2025|12/8/2025|12/9/2025|12/10/2025>
  --version                                                                       Show version information
  -?, -h, --help

Ver também

  • Last updated on