Condividi tramite

Completamento tramite tabulazione per System.CommandLine

  • Articolo

Importante

System.CommandLine è attualmente in ANTEPRIMA e questa documentazione si riferisce alla versione 2.0 beta 4. Alcune informazioni riguardano il prodotto in versione non definitiva che potrebbe essere modificato in modo sostanziale prima del rilascio. Microsoft non riconosce alcuna garanzia, espressa o implicita, in merito alle informazioni qui fornite.

Le app che usano System.CommandLine hanno il supporto predefinito per il completamento tramite tabulazione in determinate shell. Per l’abilitazione, l'utente finale deve eseguire alcuni passaggi una volta per ogni shell. Al termine dell'operazione, il completamento tramite tabulazione è automatico per i valori statici nell'app, ad esempio valori di enumerazione o valori definiti chiamando FromAmong. È inoltre possibile personalizzare il completamento tramite tabulazione ottenendo valori in modo dinamico in fase di esecuzione.

Attivare il completamento con tasto TAB

Nel computer in cui si desidera abilitare il completamento tramite tabulazione, seguire questa procedura.

Per l'interfaccia della riga di comando di .NET:

Per altre app della riga di comando basate su System.CommandLine:

  • Installare lo strumento globale dotnet-suggest.

  • Aggiungere lo script shim appropriato al profilo della shell. Potrebbe essere necessario creare un file del profilo della shell. Lo script shim inoltra le richieste di completamento dalla shell allo strumento dotnet-suggest, che delega all'app appropriata basata su System.CommandLine.

    • Per bash, aggiungere il contenuto di dotnet-suggest-shim.bash a ~/.bash_profile.

    • Per zsh, aggiungere il contenuto di dotnet-suggest-shim.zsh a ~/.zshrc.

    • Per PowerShell, aggiungere il contenuto di dotnet-suggest-shim.ps1 al profilo PowerShell. È possibile individuare il percorso previsto per il profilo PowerShell eseguendo il comando seguente nella console:

      echo $profile

Dopo aver configurato la shell dell'utente, i completamenti funzioneranno per tutte le app compilate utilizzando System.CommandLine.

Per cmd.exe in Windows (prompt dei comandi di Windows) non è disponibile alcun meccanismo di completamento tramite tabulazione collegabile, quindi non è disponibile alcuno script shim. Per altre shell, cercare un problema di GitHub con etichetta Area-Completions. Se non si trova un problema, è possibile aprirne uno nuovo.

Ottenere i valori di completamento tramite tabulazione in fase di esecuzione

Il codice seguente mostra un'app che ottiene i valori per il completamento tramite tabulazione in modo dinamico in fase di esecuzione. Il codice ottiene un elenco delle due settimane di date successive alla data corrente. L'elenco viene fornito all'opzione --date chiamando 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);
    }
}

I valori visualizzati quando si preme il tasto TAB vengono forniti come istanze CompletionItem:

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

Vengono impostate le proprietà seguenti CompletionItem:

  • Label è il valore di completamento da visualizzare.
  • SortText assicura che i valori nell'elenco vengano presentati nell'ordine corretto. Viene impostato convertendo i in una stringa a due cifre, in modo che l'ordinamento sia basato su 01, 02, 03 e così via, fino a 14. Se non si imposta questo parametro, l'ordinamento è basato su Label, che in questo esempio è in formato di data breve e non verrà ordinato correttamente.

Esistono altre proprietà CompletionItem, ad esempio Documentation e Detail, ma non sono ancora usate in System.CommandLine.

L'elenco di completamento tramite tabulazione di tipo di dinamico creato da questo codice viene visualizzato anche nell'output della guida:

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

Vedi anche

System.CommandLine panoramica