Freigeben über

Anpassen der Analyse und Validierung in System.CommandLine

Von Bedeutung

System.CommandLine befindet sich derzeit in DER VORSCHAU, und diese Dokumentation ist für Version 2.0 Beta 5 vorgesehen. Einige Informationen beziehen sich auf vorab veröffentlichte Produkte, die vor der Veröffentlichung erheblich geändert werden können. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Stellt standardmäßig eine Reihe integrierter Parser bereit, System.CommandLine 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 aufgelisteten 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 ihre Option oder Ihr Argument (oder 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

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

Angenommen, Sie haben einen Person Typ:

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

Sie können die Werte lesen und eine Instanz der Person Befehlsaktion 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.
        }
    }
};

Im Folgenden finden Sie einige Beispiele dafür, was Sie mit CustomParser einem Validator nicht tun 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