Vervollständigung per TAB-TASTE für System.CommandLine

  • Artikel

Wichtig

System.CommandLine befindet sich derzeit in der VORSCHAU, und diese Dokumentation gilt für Version 2.0 Beta 4. Einige Informationen beziehen sich auf Vorabversionen des Produkts, die vor dem Release ggf. grundlegend überarbeitet werden. Microsoft übernimmt hinsichtlich der hier bereitgestellten Informationen keine Gewährleistungen, seien sie ausdrücklich oder konkludent.

Apps, die System.CommandLine verwenden, verfügen über integrierte Unterstützung für die Vervollständigung per TAB-TASTE in bestimmten Shells. Um diese zu aktivieren, muss der oder die Endbenutzer*in einmal pro Shell einige Schritte ausführen. Nachdem der oder die Benutzer*in das erledigt hat, erfolgt die Vervollständigung per TAB-TASTE automatisch für statische Werte in Ihrer App, z. B. Enumerationswerte oder Werte, die Sie durch Aufrufen von FromAmong definieren. Sie können die Vervollständigung per TAB-TASTE auch anpassen, indem Sie zur Laufzeit dynamisch Werte abrufen.

Aktivieren der Vervollständigung mit der TAB-TASTE

Führen Sie auf dem Computer, auf dem Sie die Vervollständigung per TAB-TASTE aktivieren möchten, die folgenden Schritte aus.

Für die .NET CLI:

Für andere Befehlszeilen-Apps, die auf System.CommandLine basieren:

  • Installieren Sie das globale Tool dotnet-suggest.

  • Fügen Sie das entsprechende Shim-Skript zu Ihrem Shell-Profil hinzu. Möglicherweise müssen Sie eine Shell-Profildatei erstellen. Das Shim-Skript leitet Vervollständigungsanforderungen von Ihrer Shell an das dotnet-suggest-Tool weiter, das an die entsprechende System.CommandLine-basierte Anwendung delegiert.

    • Fügen Sie für bash den Inhalt von dotnet-suggest-shim.bash zu ~/.bash_profile hinzu.

    • Fügen Sie für zsh den Inhalt von dotnet-suggest-shim.zsh zu ~/.zshrc hinzu.

    • Fügen Sie für PowerShell den Inhalt von dotnet-suggest-shim.ps1 zu Ihrem PowerShell-Profil hinzu. Den erwarteten Pfad zu Ihrem PowerShell-Profil finden Sie, indem Sie den folgenden Befehl in Ihrer Konsole ausführen:

      echo $profile

Sobald die Benutzershell eingerichtet ist, funktioniert die Vervollständigung für alle Apps, die mit System.CommandLine erstellt werden.

Für cmd.exe unter Windows (die Windows-Eingabeaufforderung) gibt es keinen kompatiblen Vervollständigungsmechanismus per TAB-TASTE, sodass kein Shim-Skript verfügbar ist. Suchen Sie für andere Shells nach einem GitHub-Issue mit der Bezeichnung Area-Completions. Wenn Sie kein Issue finden, können Sie ein neues öffnen.

Abrufen von TAB-Vervollständigungswerten zur Laufzeit

Der folgende Code zeigt eine App, die zur Laufzeit dynamisch Werte für die Vervollständigung per TAB-TASTE abruft. Der Code ruft eine Liste mit den Datumswerten der nächsten zwei Wochen ab, die auf das aktuelle Datum folgen. Die Liste wird für die --date-Option bereitgestellt, indem AddCompletions aufgerufen wird:

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);
    }
}

Die beim Drücken der TAB-TASTE angezeigten Werte werden als CompletionItem-Instanzen bereitgestellt:

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

Die folgenden CompletionItem-Eigenschaften sind festgelegt:

  • Label ist der anzuzeigende Vervollständigungswert.
  • SortText sorgt dafür, dass die Werte in der Liste in der richtigen Reihenfolge angezeigt werden. Sie wird durch Konvertieren von i in eine zweistellige Zeichenfolge festgelegt, sodass die Sortierung auf 01, 02, 03 usw. bis 14 basiert. Wenn Sie diesen Parameter nicht festlegen, basiert die Sortierung auf dem Label-Wert, der in diesem Beispiel im kurzen Datumsformat vorliegt und nicht korrekt sortiert wird.

Es gibt andere CompletionItem-Eigenschaften, z. B. Documentation und Detail, die jedoch noch nicht in System.CommandLine verwendet werden.

Die mit diesem Code erstellte dynamische TAB-Vervollständigungsliste wird auch in der Hilfeausgabe angezeigt:

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

Weitere Informationen

System.CommandLine – Übersicht