で解析と検証をカスタマイズする方法 System.CommandLine

既定では、 System.CommandLine には、多くの一般的な型を解析できる一連の組み込みパーサーが用意されています。

• bool
• byte と sbyte
• short と ushort
• int と uint
• long と ulong
• float と double
• decimal
• DateTime と DateTimeOffset
• DateOnlyそして TimeOnly
• Guid
• FileSystemInfo、FileInfo、DirectoryInfo
• 列挙型
• リストされている型の配列とリスト

他の型はサポートされていませんが、カスタム パーサーを作成できます。 解析された値を検証することもできます。これは、入力が特定の条件を満たしていることを確認する場合に便利です。

バリデーター

すべてのオプション、引数、およびコマンドには、1 つ以上の検証コントロールを含めることができます。 検証コントロールは、解析された値が特定の条件を満たしていることを確認するために使用されます。 たとえば、数値が正であるか、文字列が空ではないことを検証できます。 複数の条件をチェックする複雑な検証コントロールを作成することもできます。

System.CommandLineのすべてのシンボル型には、検証コントロールの一覧を含むValidators プロパティがあります。 検証コントロールは、入力が解析された後に実行され、検証が失敗した場合にエラーを報告できます。

カスタム検証コードを提供するには、次の例に示すように、オプションまたは引数 (またはコマンド) で System.CommandLine.Option.Validators.Add を呼び出します。

Option<int> delayOption = new("--delay");
delayOption.Validators.Add(result =>
{
    if (result.GetValue(delayOption) < 1)
    {
        result.AddError("Must be greater than 0");
    }
});

System.CommandLine には、一般的な型を検証するために使用できる一連の組み込み検証コントロールが用意されています。

• AcceptExistingOnly - 既存のファイルまたはディレクトリに対応する値のみを受け入れるように、指定されたオプションまたは引数を構成します。
• AcceptLegalFileNamesOnly - 有効なファイル名を表す値のみを受け入れるように、指定されたオプションまたは引数を構成します。
• AcceptOnlyFromAmong - 指定した値セットの値のみを受け入れるように、指定されたオプションまたは引数を構成します。

カスタム パーサー

カスタム パーサーは、複合型など、既定のパーサーを使用しない型を解析するために必要です。 組み込みのパーサーとは異なる方法で、サポートされている型を解析するために使用することもできます。

Person型があるとします。

public class Person
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
}

コマンド アクションでは、値を読み取り、 Person のインスタンスを作成できます。

rootCommand.SetAction(parseResult =>
{
    Person person = new()
    {
        FirstName = parseResult.GetValue(firstNameOption),
        LastName = parseResult.GetValue(lastNameOption)
    };
    DoRootCommand(parseResult.GetValue(fileOption), person);
});

カスタム パーサーを使用すると、プリミティブ値を取得するのと同じ方法でカスタム型を取得できます。

Option<Person?> personOption = new("--person")
{
    Description = "An option whose argument is parsed as a Person",
    CustomParser = result =>
    {
        if (result.Tokens.Count != 2)
        {
            result.AddError("--person requires two arguments");
            return null;
        }
        return new Person
        {
            FirstName = result.Tokens.First().Value,
            LastName = result.Tokens.Last().Value
        };
    }
};

入力を解析して検証する場合は、次の例に示すように、 CustomParser デリゲートを使用します。

Option<int> delayOption = new("--delay")
{
    Description = "An option whose argument is parsed as an int.",
    CustomParser = result =>
    {
        if (!result.Tokens.Any())
        {
            return 42;
        }

        if (int.TryParse(result.Tokens.Single().Value, out var delay))
        {
            if (delay < 1)
            {
                result.AddError("Must be greater than 0");
            }
            return delay;
        }
        else
        {
            result.AddError("Not an int.");
            return 0; // Ignored.
        }
    }
};

検証コントロールでは実行できない CustomParser で実行できる操作の例を次に示します。

• 他の種類の入力文字列を解析します (たとえば、"1,2,3" を int[]に解析します)。
• 動的なアリティ。 たとえば、文字列配列として定義されている 2 つの引数があり、コマンド ライン入力で文字列のシーケンスを処理する必要がある場合、 System.CommandLine.Parsing.ArgumentResult.OnlyTake メソッドを使用すると、引数間で入力文字列を動的に分割できます。

こちらも参照ください

• 結果を解析して呼び出す方法
• System.CommandLine の概要