Teilen über

Wie man die Analyse und Validierung in System.CommandLine anpasst

Standardmäßig bietet System.CommandLine ein Set von integrierten Parsern, die viele gängige Typen analysieren können:

  • bool
  • byte und sbyte
  • short und ushort
  • int und uint
  • long und ulong
  • float und double
  • decimal
  • DateTime und DateTimeOffset
  • DateOnlyund TimeOnly
  • Guid
  • FileSystemInfo, FileInfo und DirectoryInfo
  • Enumerationen
  • Arrays und Listen der aufgeführten Typen

Andere Typen werden nicht unterstützt, sie können jedoch benutzerdefinierte Parser erstellen. Sie können auch die analysierten Werte überprüfen, was hilfreich ist, wenn Sie sicherstellen möchten, dass die Eingabe bestimmte Kriterien erfüllt.

Validatoren

Jede Option, jedes Argument und jeder Befehl kann mindestens ein Validator haben. Validatoren werden verwendet, um sicherzustellen, dass der analysierte Wert bestimmte Kriterien erfüllt. Sie können z. B. überprüfen, ob eine Zahl positiv ist oder dass eine Zeichenfolge nicht leer ist. Sie können auch komplexe Validatoren erstellen, die auf mehrere Bedingungen überprüfen.

Jeder Symboltyp in System.CommandLine verfügt über eine Validators Eigenschaft, die eine Liste von Validatoren enthält. Die Validatoren werden ausgeführt, nachdem die Eingabe analysiert wurde, und sie können einen Fehler melden, wenn die Überprüfung fehlschlägt.

Um benutzerdefinierten Überprüfungscode bereitzustellen, rufen Sie System.CommandLine.Option.Validators.Add auf Ihrer Option, Ihrem Argument oder Ihrem Befehl auf, wie im folgenden Beispiel gezeigt:

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

System.CommandLine stellt einen Satz integrierter Validatoren bereit, mit denen allgemeine Typen überprüft werden können:

  • AcceptExistingOnly – konfiguriert die angegebene Option oder das angegebene Argument so, dass nur Werte akzeptiert werden, die einer vorhandenen Datei oder einem vorhandenen Verzeichnis entsprechen.
  • AcceptLegalFileNamesOnly – konfiguriert die angegebene Option oder das argument so, dass nur Werte akzeptiert werden, die legale Dateinamen darstellen.
  • AcceptOnlyFromAmong – konfiguriert die angegebene Option oder das angegebene Argument so, dass nur Werte aus einer bestimmten Gruppe von Werten akzeptiert werden.

Benutzerdefinierte Parser

Um Typen ohne Standardparser zu analysieren, z. B. komplexe Typen, benötigen Sie einen benutzerdefinierten Parser. Benutzerdefinierte Parser können auch verwendet werden, um unterstützte Typen auf eine andere Weise zu analysieren als die integrierten Parser.

Angenommen, Sie haben einen Typ Person:

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

Sie können die Werte lesen und in der Befehlsaktion eine Instanz von Person erstellen.

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

Mit einem benutzerdefinierten Parser können Sie einen benutzerdefinierten Typ auf die gleiche Weise abrufen, wie Grundtypenwerte abgerufen werden:

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

Wenn Sie die Eingabe analysieren und überprüfen möchten, verwenden Sie die CustomParser Stellvertretung, wie im folgenden Beispiel gezeigt:

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

Hier sind einige Beispiele dafür, was Sie mit CustomParser tun können, was Sie mit einem Validator nicht können.

  • Analysieren Sie andere Arten von Eingabezeichenfolgen (z. B. analysieren Sie "1,2,3" in int[]).
  • Dynamische Arität. Wenn Sie z. B. zwei Argumente haben, die als Zeichenfolgenarrays definiert sind und eine Abfolge von Zeichenfolgen in der Befehlszeileneingabe verarbeiten müssen, können Sie mit der System.CommandLine.Parsing.ArgumentResult.OnlyTake Methode die Eingabezeichenfolgen dynamisch zwischen den Argumenten aufteilen.

Siehe auch

  • Last updated on