Dokončování tabulátoru pro System.CommandLine

Aplikace, které používají System.CommandLine, mají vestavěnou podporu pro automatické doplňování tabulátorů v některých shellech. Pokud ho chcete povolit, musí koncový uživatel provést několik kroků jednou pro každé shellové prostředí. Po dokončení je dokončení tabulátoru automatické pro statické hodnoty v aplikaci, například výčtové hodnoty nebo hodnoty definované voláním AcceptOnlyFromAmong(String[]). Dokončování tabulátoru můžete také přizpůsobit tak, že za běhu poskytnete hodnoty dynamicky.

Povolit dokončování tabulátoru

Na počítači, na kterém chcete (koncový uživatel) povolit dokončování tabulátoru, postupujte podle těchto kroků.

Pro .NET CLI:

Pro další aplikace příkazového řádku postavené na System.CommandLine:

  • dotnet-suggest Nainstalujte globální nástroj:

    dotnet tool install -g dotnet-suggest

  • Přidejte do shellového profilu příslušný skript shim. Možná budete muset vytvořit shell profilový soubor. Propojovací skript předá požadavky na dokončení z prostředí do dotnet-suggest nástroje, který je deleguje na příslušnou System.CommandLine aplikaci.

    • Přidejte obsah souboru bash do souboru ~/.bash_profile.

    • Pro zshpřidejte obsah dotnet-suggest-shim.zsh do ~/.zshrc.

    • V powershellu přidejte obsah dotnet-suggest-shim.ps1 do profilu PowerShellu a restartujte PowerShell. Očekávanou cestu k profilu PowerShellu najdete pomocí následujícího příkazu:

      echo $profile

  • Zaregistrujte aplikaci voláním dotnet-suggest register --command-path $executableFilePath, kde $executableFilePath je cesta ke spustitelnému souboru aplikace.

Po nastavení prostředí uživatele a registraci spustitelného souboru budou dokončení fungovat pro všechny aplikace vytvořené pomocí System.CommandLine.

Pro cmd.exe ve Windows (příkazový řádek systému Windows) neexistuje žádný mechanismus pro rozšiřitelné dokončování příkazů pomocí klávesy Tab, takže není k dispozici žádná náhrada skriptem. V případě jiných prostředí vyhledejte problém GitHubu, který je označený Area-Completions. Pokud problém nenajdete, můžete otevřít nový.

Získání hodnot dokončení tabulátoru za běhu

Následující kód ukazuje aplikaci, která dynamicky načítá hodnoty pro dokončování tabulátoru za běhu. Kód získá seznam kalendářních dat následujícího týdne za aktuálním datem. Seznam je poskytován do možnosti --date voláním 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)}");
        });
    }
}

Hodnoty zobrazené při stisknutí klávesy Tab jsou k dispozici jako CompletionItem instance:

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

Jsou nastaveny následující CompletionItem vlastnosti:

  • Label je hodnota dokončení, která se má zobrazit.
  • SortText zajišťuje, aby se hodnoty v seznamu zobrazovaly ve správném pořadí. Nastaví se tím, že se i převede na dvouciferný řetězec, aby řazení bylo založeno na hodnotách 01, 02, 03, atd., až po 14. Pokud tento parametr nenastavíte, řazení je založeno na Label, což v tomto příkladu je ve formátu krátkého data a nebude se řadit správně.

Existují další CompletionItem vlastnosti, například Documentation a Detail, ale ještě nejsou použity v System.CommandLine.

Seznam dynamického dokončování tabulátoru vytvořený tímto kódem se také zobrazí ve výstupu nápovědy:

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

Viz také

  • Last updated on