Condividi tramite

Come personalizzare l'analisi e la convalida in System.CommandLine

Importante

System.CommandLine è attualmente disponibile in ANTEPRIMA e questa documentazione è per la versione 2.0 beta 5. Alcune informazioni riguardano il prodotto in fase di pre-rilascio che potrebbe essere modificato in modo sostanziale prima del rilascio. Microsoft non fornisce alcuna garanzia, espressa o implicita, in relazione alle informazioni fornite qui.

Per impostazione predefinita, System.CommandLine fornisce un set di parser predefiniti che possono analizzare molti tipi comuni:

  • bool
  • byte e sbyte
  • short e ushort
  • int e uint
  • long e ulong
  • float e double
  • decimal
  • DateTime e DateTimeOffset
  • DateOnlye TimeOnly
  • Guid
  • FileSystemInfo, FileInfo e DirectoryInfo
  • enumerazioni
  • matrici ed elenchi dei tipi elencati

Altri tipi non sono supportati, ma è possibile creare parser personalizzati. È anche possibile convalidare i valori analizzati, utile quando si vuole assicurarsi che l'input soddisfi determinati criteri.

Validatori

Ogni opzione, argomento e comando può avere uno o più validator. I validator vengono usati per garantire che il valore analizzato soddisfi determinati criteri. Ad esempio, è possibile verificare che un numero sia positivo o che una stringa non sia vuota. È anche possibile creare validator complessi che controllano più condizioni.

Ogni tipo di simbolo in System.CommandLine ha una Validators proprietà che contiene un elenco di validator. I validator vengono eseguiti dopo l'analisi dell'input e possono segnalare un errore se la convalida non riesce.

Per fornire codice di convalida personalizzato, chiamare System.CommandLine.Option.Validators.Add sull'opzione o sull'argomento (o comando), come mostrato nell'esempio seguente.

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

System.CommandLine fornisce un set di validator predefiniti che possono essere usati per convalidare i tipi comuni:

  • AcceptExistingOnly : configura l'opzione o l'argomento specificato per accettare solo i valori corrispondenti a un file o a una directory esistente.
  • AcceptLegalFileNamesOnly : configura l'opzione o l'argomento specificato per accettare solo valori che rappresentano nomi di file legali.
  • AcceptOnlyFromAmong : configura l'opzione o l'argomento specificato per accettare solo i valori di un set specificato di valori.

Parser personalizzati

I parser personalizzati sono necessari per analizzare i tipi senza parser predefinito, ad esempio tipi complessi. Possono anche essere usati per analizzare i tipi supportati in modo diverso rispetto ai parser predefiniti.

Si supponga di avere un Person tipo:

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

È possibile leggere i valori e creare un'istanza di Person nell'azione del comando.

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

Con un parser personalizzato, è possibile ottenere un tipo personalizzato nello stesso modo in cui si ottengono valori primitivi:

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

Se si vuole analizzare e convalidare l'input, usare il CustomParser delegato , come illustrato nell'esempio seguente:

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

Ecco alcuni esempi di operazioni che è possibile eseguire con CustomParser che non si possono fare con un validator:

  • Analizzare altri tipi di stringhe di input( ad esempio, analizzare "1,2,3" in int[]).
  • Arità dinamica. Ad esempio, se sono presenti due argomenti definiti come matrici di stringhe e è necessario gestire una sequenza di stringhe nell'input della riga di comando, il System.CommandLine.Parsing.ArgumentResult.OnlyTake metodo consente di dividere dinamicamente le stringhe di input tra gli argomenti.

Vedere anche