System.CommandLine のタブ補完

System.CommandLineを使用するアプリには、特定のシェルでのタブ補完のサポートが組み込まれています。 これを有効にするには、エンド ユーザーがシェルごとに 1 回、いくつかの手順を実行する必要があります。 これが完了すると、アプリ内の静的な値 (列挙型の値や、 System.CommandLine.Option<T>.AcceptOnlyFromAmongを呼び出して定義された値など) に対してタブ補完が自動的に行われます。 実行時に値を動的に指定することで、タブ補完をカスタマイズすることもできます。

タブ補完を有効にする

タブ補完を有効にするコンピューターで、次の手順に従います。

.NET CLI の場合:

• タブ補完を有効にする方法を参照してください。

System.CommandLine上に構築されたその他のコマンドライン アプリの場合:

• dotnet-suggest グローバル ツールをインストールします。

• シェル プロファイルに適切な shim スクリプトを追加します。 シェル プロファイル ファイルを作成することが必要な場合があります。 shim スクリプトは、シェルから dotnet-suggest ツールに完了要求を転送し、適切な System.CommandLine ベースのアプリに委任します。

  • bashの場合は、dotnet-suggest-shim.bash の内容を ~/.bash_profile に追加します。

  • zshの場合は、dotnet-suggest-shim.zsh の内容を ~/.zshrc に追加します。

  • PowerShell の場合は、 dotnet-suggest-shim.ps1 の内容を PowerShell プロファイルに追加します。 コンソールで次のコマンドを実行すると、PowerShell プロファイルへの予想されるパスを確認できます。

    echo $profile
    

• dotnet-suggest register --command-path $executableFilePathを呼び出してアプリを登録します。ここで、$executableFilePathはアプリの実行可能ファイルへのパスです。

ユーザーのシェルが設定され、実行可能ファイルが登録されると、 System.CommandLineを使用してビルドされたすべてのアプリに対して完了が機能します。

Windows 上の cmd.exe (Windows コマンド プロンプト) の場合、プラグインできるタブ補完メカニズムがないため、shim スクリプトは使用できません。 その他のシェルについては、Area-Completionsラベルが付いている GitHub の問題を探します。 問題が見つからない場合は、 新しい問題を開くことができます。

実行時にタブ補完値を取得する

次のコードは、実行時にタブ補完の値を動的に取得するアプリを示しています。 このコードは、現在の日付の後の次の 2 週間の日付の一覧を取得します。 リストは、--dateを呼び出すことによって、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)}");
        });
    }
}

Tab キーが押されたときに表示される値は、 CompletionItem インスタンスとして提供されます。

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

次の CompletionItem プロパティが設定されます。

• Label は、表示される完了値です。
• SortText は、リスト内の値が正しい順序で表示されることを保証します。 これは、 i を 2 桁の文字列に変換することによって設定されます。これにより、並べ替えは 01、02、03、14 に基づきます。 このパラメーターを設定しない場合、並べ替えは Labelに基づきます。この例では短い日付形式であり、正しく並べ替えされません。

CompletionItemやDocumentationなど、他のDetailプロパティがありますが、System.CommandLineではまだ使用されていません。

このコードによって作成された動的タブ補完リストもヘルプ出力に表示されます。

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

こちらも参照ください

System.CommandLine の概要