Бөлісу құралы:

Настройка синтаксического анализа и проверки в System.CommandLine

По умолчанию System.CommandLine предоставляет набор встроенных средств синтаксического анализа, которые могут анализировать множество распространенных типов:

  • bool
  • byte и sbyte.
  • short и ushort.
  • int и uint.
  • long и ulong.
  • float и double.
  • decimal
  • DateTime и DateTimeOffset.
  • DateOnlyи TimeOnly
  • Guid
  • FileSystemInfo, FileInfo и DirectoryInfo
  • перечисления
  • массивы и списки перечисленных типов

Другие типы не поддерживаются, но для них можно создавать пользовательские средства синтаксического анализа. Вы также можете проверить проанализированные значения, что полезно, если требуется убедиться, что входные данные соответствуют определенным критериям.

Валидаторы

Каждый параметр, аргумент и команда могут иметь один или несколько проверяющих элементов. Валидаторы используются для обеспечения соответствия распарсенному значению определенным критериям. Например, можно проверить, является ли число положительным или что строка не пуста. Кроме того, можно создать сложные проверяющие средства, которые проверяют наличие нескольких условий.

Каждый тип символа в 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[]).
  • Динамическая арность. Например, если у вас есть два аргумента, которые определяются как массивы строк, и необходимо обрабатывать последовательность строк в входных данных командной строки, System.CommandLine.Parsing.ArgumentResult.OnlyTake метод позволяет динамически разделить входные строки между аргументами.

См. также

  • Last updated on