Conclusão da guia para System.CommandLine

Importante

System.CommandLine está atualmente em VERSÃO PRÉVIA e essa documentação é para a versão 2.0 beta 5. Algumas informações referem-se 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 guia em determinados shells. Para habilitá-lo, o usuário final deve executar algumas etapas uma vez por shell. Depois que isso for concluído, a conclusão da guia será automática para valores estáticos em seu aplicativo, como valores ou valores de enumeração definidos pela chamada System.CommandLine.Option<T>.AcceptOnlyFromAmong. Você também pode personalizar a conclusão da guia fornecendo valores dinamicamente em runtime.

Ativar o recurso auto-completar com TAB

No computador em que você deseja habilitar a conclusão da guia, siga estas etapas.

Para a CLI do .NET:

• Veja Como habilitar a conclusão da guia.

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

• Instale a dotnet-suggest ferramenta global.

• Adicione o script shim apropriado ao seu perfil de shell. Talvez seja necessário criar um arquivo de perfil de shell. O script shim encaminha solicitações de conclusão do shell para a ferramenta, que dotnet-suggest as delega ao aplicativo baseado em apropriado 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 de dotnet-suggest-shim.ps1 ao seu perfil do PowerShell. Você pode encontrar o caminho esperado para o perfil do PowerShell executando o seguinte comando em seu console:

    echo $profile
    

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

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

Para cmd.exe no Windows (o Prompt de Comando do Windows) não há nenhum mecanismo de conclusão de guia pluggá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 conclusão da guia em tempo de execução

O código a seguir mostra um aplicativo que recupera valores para conclusão de guia 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 chamando 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 sejam 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 você não definir esse parâmetro, a Labelclassificação será baseada no , que neste exemplo está em formato de data curta e não será classificado corretamente.

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

A lista de preenchimento de guia dinâmica 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

Consulte também

visão geral System.CommandLine