Partager via

Comment personnaliser l’analyse et la validation dans System.CommandLine

Par défaut, System.CommandLine fournit un ensemble d’analyseurs intégrés qui peuvent analyser de nombreux types courants :

  • bool
  • byte et sbyte
  • short et ushort
  • int et uint
  • long et ulong
  • float et double
  • decimal
  • DateTime et DateTimeOffset
  • DateOnlyet TimeOnly
  • Guid
  • FileSystemInfo, FileInfo et DirectoryInfo
  • , énumérations
  • tableaux et listes des types répertoriés

D’autres types ne sont pas pris en charge, mais vous pouvez créer des analyseurs personnalisés pour eux. Vous pouvez également valider les valeurs analysées, ce qui est utile lorsque vous souhaitez vous assurer que l’entrée répond à certains critères.

Validateurs

Chaque option, argument et commande peut avoir un ou plusieurs validateurs. Les validateurs sont utilisés pour s’assurer que la valeur analysée répond à certains critères. Par exemple, vous pouvez vérifier qu’un nombre est positif ou qu’une chaîne n’est pas vide. Vous pouvez également créer des validateurs complexes qui vérifient sur plusieurs conditions.

Chaque type System.CommandLine de symbole a une Validators propriété qui contient une liste de validateurs. Les validateurs sont exécutés après l’analyse de l’entrée et peuvent signaler une erreur en cas d’échec de la validation.

Pour fournir du code de validation personnalisé, appelez System.CommandLine.Option.Validators.Add votre option ou argument (ou commande), comme illustré dans l’exemple suivant :

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

System.CommandLine fournit un ensemble de validateurs intégrés qui peuvent être utilisés pour valider les types courants :

  • AcceptExistingOnly - configure l’option ou l’argument donné pour accepter uniquement les valeurs correspondant à un fichier ou répertoire existant.
  • AcceptLegalFileNamesOnly - configure l’option ou l’argument donné pour accepter uniquement les valeurs représentant des noms de fichiers juridiques.
  • AcceptOnlyFromAmong - configure l’option ou l’argument donné pour accepter uniquement les valeurs d’un ensemble de valeurs spécifié.

Analyseurs personnalisés

Pour analyser les types sans analyseur par défaut, comme les types complexes, vous avez besoin d’un analyseur personnalisé. Les analyseurs personnalisés peuvent également être utilisés pour analyser les types pris en charge d’une manière différente de celle des analyseurs intégrés.

Supposons que vous avez un type Person :

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

Vous pouvez lire les valeurs et créer une instance de Person dans l'action de commande :

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

Avec un analyseur personnalisé, vous pouvez obtenir un type personnalisé de la même façon que vous obtenez des valeurs primitives :

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 vous souhaitez analyser ainsi que valider l’entrée, utilisez le CustomParser délégué, comme illustré dans l’exemple suivant :

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

Voici quelques exemples de ce que vous pouvez faire avec CustomParser ce que vous ne pouvez pas faire avec un validateur :

  • Analysez d’autres types de chaînes d’entrée (par exemple, analysez « 1,2,3 » en int[]).
  • Arité dynamique. Par exemple, si vous avez deux arguments définis en tant que tableaux de chaînes et que vous devez gérer une séquence de chaînes dans l’entrée de ligne de commande, la System.CommandLine.Parsing.ArgumentResult.OnlyTake méthode vous permet de diviser dynamiquement les chaînes d’entrée entre les arguments.

Voir aussi

  • Last updated on