System.CommandLine のタブ補完

[アーティクル]
06/08/2023

重要

System.CommandLine は現在プレビュー段階であり、このドキュメントはバージョン 2.0 beta 4 を対象としています。一部の情報は、リリース前に大きく変更される可能性があるプレリリースされた製品に関するものです。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。

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

タブ補完を有効にする

タブ補完を有効にするマシン上で、次の手順を実行します。

.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
```

ユーザーのシェルを設定すると、System.CommandLine を使って構築されたすべてのアプリで補完が機能するようになります。

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

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

次のコードは、実行時にタブ補完の値を動的に取得するアプリを示しています。このコードを使うと、現在の日付の次の 2 週間の日付一覧を取得します。この一覧を --date オプションに渡すには、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);
    }
}

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 のタブ補完

タブ補完を有効にする

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

関連項目

その他のリソース