Så här anpassar du parsning och validering i System.CommandLine

Som standard System.CommandLine tillhandahåller en uppsättning inbyggda parsers som kan parsa många vanliga typer:

• bool
• byte och sbyte
• short och ushort
• int och uint
• long och ulong
• float och double
• decimal
• DateTime och DateTimeOffset
• DateOnlyoch TimeOnly
• Guid
• FileSystemInfo, FileInfo och DirectoryInfo
• uppräkningar
• matriser och listor över de listade typerna

Andra typer stöds inte, men du kan skapa anpassade parsers för dem. Du kan också verifiera de tolkade värdena, vilket är användbart när du vill se till att indata uppfyller vissa kriterier.

Validerare

Varje alternativ, argument och kommando kan ha en eller flera validatorer. Validatorer används för att säkerställa att det parsade värdet uppfyller vissa kriterier. Du kan till exempel verifiera att ett tal är positivt eller att en sträng inte är tom. Du kan också skapa komplexa validatorer som kontrollerar mot flera villkor.

Varje symboltyp i System.CommandLine har en Validators egenskap som innehåller en lista över validerare. Validatorerna körs när indata parsas och de kan rapportera ett fel om verifieringen misslyckas.

Om du vill ange anpassad valideringskod anropar System.CommandLine.Option.Validators.Add du ditt alternativ eller argument (eller kommando) enligt följande exempel:

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

System.CommandLine innehåller en uppsättning inbyggda validatorer som kan användas för att verifiera vanliga typer:

• AcceptExistingOnly – konfigurerar det angivna alternativet eller argumentet för att endast acceptera värden som motsvarar en befintlig fil eller katalog.
• AcceptLegalFileNamesOnly – konfigurerar det angivna alternativet eller argumentet för att endast acceptera värden som representerar juridiska filnamn.
• AcceptOnlyFromAmong – konfigurerar det angivna alternativet eller argumentet för att endast acceptera värden från en angiven uppsättning värden.

Anpassade tolkar

Om du vill parsa typer utan standardparser, till exempel komplexa typer, behöver du en anpassad parser. Anpassade parsers kan också användas för att parsa typer som stöds på ett annat sätt än de inbyggda parsarna.

Anta att du har en Person typ:

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

Du kan läsa värdena och skapa en instans av Person i kommandoåtgärden:

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

Med en anpassad parser kan du hämta en anpassad typ på samma sätt som du får primitiva värden:

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

Om du vill parsa och verifiera indata, använder du delegaten CustomParser, som du ser i följande exempel:

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

Här följer några exempel på vad du kan göra med CustomParser att du inte kan göra med en validator:

• Parsa andra typer av indatasträngar (till exempel parsa "1,2,3" i int[]).
• Dynamisk aritet. Om du till exempel har två argument som definieras som strängmatriser och du måste hantera en sekvens med strängar i kommandoradsindata kan System.CommandLine.Parsing.ArgumentResult.OnlyTake du dynamiskt dela upp indatasträngarna mellan argumenten.

Se även

• Så här parsar och anropar du resultatet
• System.CommandLine överblick