Compartir a través de

Cómo personalizar el análisis y la validación en System.CommandLine

Importante

System.CommandLine actualmente está en versión preliminar y esta documentación es para la versión 2.0 beta 5. Cierta información se relaciona con el producto de versión preliminar que puede modificarse sustancialmente antes de su lanzamiento. Microsoft no ofrece ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

De forma predeterminada, System.CommandLine proporciona un conjunto de analizadores integrados que pueden analizar muchos tipos comunes:

  • bool
  • byte y sbyte
  • short y ushort
  • int y uint
  • long y ulong
  • float y double
  • decimal
  • DateTime y DateTimeOffset
  • DateOnlyy TimeOnly
  • Guid
  • FileSystemInfo, FileInfo y DirectoryInfo
  • enumeraciones
  • matrices y listas de los tipos enumerados

No se admiten otros tipos, pero puede crear analizadores personalizados para ellos. También puede validar los valores analizados, lo que resulta útil cuando desea asegurarse de que la entrada cumple determinados criterios.

Validadores

Cada opción, argumento y comando puede tener uno o varios validadores. Los validadores se usan para asegurarse de que el valor analizado cumple determinados criterios. Por ejemplo, puede validar que un número es positivo o que una cadena no está vacía. También puede crear validadores complejos que comprueben varias condiciones.

Cada tipo de símbolo de System.CommandLine tiene una Validators propiedad que contiene una lista de validadores. Los validadores se ejecutan después de analizar la entrada y pueden notificar un error si se produce un error en la validación.

Para proporcionar código de validación personalizado, llame a System.CommandLine.Option.Validators.Add la opción o argumento (o comando), como se muestra en el ejemplo siguiente:

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

System.CommandLine proporciona un conjunto de validadores integrados que se pueden usar para validar tipos comunes:

  • AcceptExistingOnly : configura una opción o argumento dados para aceptar solo los valores correspondientes a un archivo o directorio existente.
  • AcceptLegalFileNamesOnly : configura una opción o argumento dados para aceptar solo valores que representan nombres de archivo legales.
  • AcceptOnlyFromAmong : configura una opción o argumento dados para aceptar solo valores de un conjunto de valores especificado.

Analizadores personalizados

Los analizadores personalizados son necesarios para analizar tipos sin analizador predeterminado, como tipos complejos. También se pueden usar para analizar los tipos admitidos de una manera diferente a los analizadores integrados.

Supongamos que tiene un Person tipo:

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

Puede leer los valores y crear una instancia de Person en la acción de comando:

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

Con un analizador personalizado, puede obtener un tipo personalizado de la misma manera que obtiene valores primitivos:

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

Si desea analizar y validar la entrada, use el CustomParser delegado, como se muestra en el ejemplo siguiente:

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

Estos son algunos ejemplos de lo que puede hacer con CustomParser que no puede hacer con un validador:

  • Analice otros tipos de cadenas de entrada (por ejemplo, analice "1,2,3" en int[]).
  • Aridad dinámica. Por ejemplo, si tiene dos argumentos definidos como matrices de cadenas y tiene que controlar una secuencia de cadenas en la entrada de la línea de comandos, el System.CommandLine.Parsing.ArgumentResult.OnlyTake método permite dividir dinámicamente las cadenas de entrada entre los argumentos.

Consulte también