Sdílet prostřednictvím

Přizpůsobení analýzy a ověřování v System.CommandLine

Ve výchozím nastavení poskytuje System.CommandLine sadu předdefinovaných analyzátorů, které můžou parsovat mnoho běžných typů.

  • bool
  • byte a sbyte
  • short a ushort
  • int a uint
  • long a ulong
  • float a double
  • decimal
  • DateTime a DateTimeOffset
  • DateOnlya TimeOnly
  • Guid
  • FileSystemInfo, FileInfo a DirectoryInfo
  • výčty
  • pole a seznamy uvedených typů

Jiné typy nejsou podporované, ale můžete pro ně vytvořit vlastní analyzátory. Můžete také ověřit analyzované hodnoty, což je užitečné, když chcete zajistit, aby vstup splňoval určitá kritéria.

Ověřovatele

Každá možnost, argument a příkaz můžou mít jeden nebo více validátorů. Validátory se používají k zajištění toho, aby parsovaná hodnota splňovala určitá kritéria. Můžete například ověřit, že číslo je kladné nebo že řetězec není prázdný. Můžete také vytvořit komplexní validátory, které kontrolují více podmínek.

Každý typ symbolu System.CommandLineValidators má vlastnost, která obsahuje seznam validátorů. Validátory se spustí po analýze vstupu a můžou ohlásit chybu, pokud ověření selže.

Pokud chcete zadat vlastní ověřovací kód, zavolejte System.CommandLine.Option.Validators.Add na svou možnost nebo argument (nebo příkaz), jak je znázorněno v následujícím příkladu:

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

System.CommandLine poskytuje sadu předdefinovaných validátorů, které lze použít k ověření běžných typů:

  • AcceptExistingOnly – nakonfiguruje danou možnost nebo argument tak, aby přijímal pouze hodnoty odpovídající existujícímu souboru nebo adresáři.
  • AcceptLegalFileNamesOnly – nakonfiguruje danou možnost nebo argument tak, aby přijímal pouze hodnoty představující názvy právních souborů.
  • AcceptOnlyFromAmong – nakonfiguruje danou možnost nebo argument tak, aby přijímal pouze hodnoty ze zadané sady hodnot.

Vlastní analyzátory

K analýze typů bez výchozího analyzátoru, jako jsou například komplexní typy, potřebujete vlastní analyzátor. Vlastní analyzátory lze také použít k analýze podporovaných typů jiným způsobem než předdefinované analyzátory.

Představte si, že máte Person typ:

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

Hodnoty si můžete přečíst a vytvořit instanci Person v akci příkazu:

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

Pomocí vlastního analyzátoru můžete získat vlastní typ stejným způsobem, jakým získáte primitivní hodnoty:

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

Pokud chcete parsovat i ověřit vstup, použijte delegáta CustomParser , jak je znázorněno v následujícím příkladu:

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

Tady je několik příkladů toho, co můžete dělat s CustomParser, ale nemůžete s validátorem.

  • Parsovat další druhy vstupních řetězců (například parsovat "1,2,3" do int[]).
  • Dynamická arity. Pokud máte například dva argumenty, které jsou definovány jako pole řetězců a musíte zpracovat posloupnost řetězců ve vstupu příkazového řádku, System.CommandLine.Parsing.ArgumentResult.OnlyTake metoda umožňuje dynamicky rozdělit vstupní řetězce mezi argumenty.

Viz také

  • Last updated on