Partilhar via

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

Importante

System.CommandLine está atualmente em pré-visualização e esta documentação destina-se à versão 2.0 beta 5. Algumas informações estão relacionadas ao produto de pré-lançamento que pode ser substancialmente modificado antes de ser lançado. A Microsoft não oferece garantias, expressas ou implícitas, em relação às informações fornecidas aqui.

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 System.CommandLine.Option<T>.AcceptOnlyFromAmong. 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 pretende ativar a conclusão automática de comandos, siga os seguintes passos.

Para a CLI do .NET:

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

  • Instale a ferramenta global 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, 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 seguinte comando no console:

      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 há nenhum mecanismo de conclusão de guia conectável, portanto, nenhum script de correção está disponível. Para outros shells, procure uma questão no GitHub rotulada como 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 obtém uma lista das próximas duas semanas de datas após a data 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 instâncias:

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. 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 não definir este parâmetro, a ordenação será baseada no Label, que neste exemplo está no formato de data abreviada e não será ordenada 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.
  <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

Ver também

System.CommandLine Visão geral