Compartilhar via

Preenchimento com Tab para System.CommandLine

  • Artigo

Importante

Atualmente, System.CommandLine está em VERSÃO PRÉVIA, e essa documentação é para a versão 2.0 beta 4. Algumas informações estão relacionadas a produtos de pré-lançamento que poderão ser substancialmente modificados antes do lançamento. A Microsoft não oferece garantias, expressas ou implícitas, das informações aqui fornecidas.

Os aplicativos que usam System.CommandLine têm suporte interno para o preenchimento com Tab em determinados shells. Para habilitá-lo, o usuário final precisa executar algumas etapas uma vez por shell. Depois que o usuário faz isso, o preenchimento com Tab é automático para valores estáticos no seu aplicativo, como valores de enumeração ou valores que você define chamando FromAmong. Você também pode personalizar o preenchimento com Tab ao obter valores dinamicamente no runtime.

Ativar o recurso auto-completar com TAB

No computador em que você deseja habilitar o preenchimento com Tab, siga as etapas a seguir.

Para a CLI do .NET:

Para outros aplicativos de linha de comando criados em System.CommandLine:

  • Instale a ferramenta global dotnet-suggest.

  • Adicionar o script de shim apropriado ao seu perfil de shell. Talvez você precise criar um arquivo de perfil de shell. O script de shim encaminha solicitações de conclusão do seu shell para a ferramenta dotnet-suggest, que delega ao aplicativo baseado em System.CommandLine apropriado.

    • 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, adicione o conteúdo do dotnet-suggest-shim.ps1 ao seu perfil do PowerShell. Você pode encontrar o caminho esperado para seu perfil do PowerShell executando o comando a seguir em seu console:

      echo $profile

Depois que o shell do usuário for configurado, as conclusões funcionarão para todos os aplicativos criados usando-se System.CommandLine.

Para cmd.exe no Windows (o Prompt de Comando do Windows), não há nenhum mecanismo de preenchimento com Tab plugável, portanto, nenhum script shim está disponível. Para outros shells, procure um problema do GitHub rotulado Area-Completions. Se você não encontrar um problema, poderá abrir um novo.

Obter valores de preenchimento com Tab em tempo de execução

O código a seguir mostra um aplicativo que obtém valores para o preenchimento com Tab dinamicamente em runtime. O código obtém uma lista das próximas duas semanas de datas após a data atual. A lista é fornecida à opção --date ao chamar AddCompletions:

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

await new DateCommand().InvokeAsync(args);

class DateCommand : Command
{
    private Argument<string> subjectArgument = 
        new ("subject", "The subject of the appointment.");
    private Option<DateTime> dateOption = 
        new ("--date", "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.AddArgument(subjectArgument);
        this.AddOption(dateOption);

        dateOption.AddCompletions((ctx) => {
            var today = System.DateTime.Today;
            var dates = new List<CompletionItem>();
            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.SetHandler((subject, date) =>
            {
                Console.WriteLine($"Scheduled \"{subject}\" for {date}");
            },
            subjectArgument, dateOption);
    }
}

Os valores mostrados quando a tecla tab é pressionada são fornecidos como instâncias CompletionItem:

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

As seguintes propriedades CompletionItem são definidas:

  • Label é o valor de conclusão a ser mostrado.
  • SortText garante que os valores na lista sejam apresentados na ordem certa. Ele é definido convertendo i em uma cadeia de caracteres de dois dígitos, de modo que a classificação seja baseada em 01, 02, 03 e assim por diante, até 14. Se você não definir esse parâmetro, a classificação será baseada no Label, que neste exemplo está em formato de data curto e não classificará corretamente.

Há outras propriedades CompletionItem, como Documentation e Detail, mas elas ainda não são usadasSystem.CommandLine.

A lista dinâmica de preenchimento com Tab criada por esse código também aparece na saída da 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.
  <2/4/2022|2/5/2022|2/6/2022|2/7/2022|2/8/2022|2/9/2022|2/10/2022>
  --version                                                                       Show version information
  -?, -h, --help

Confira também

System.CommandLine overview