Parseren en aanroepen in System.CommandLine

2025-06-19

Belangrijk

System.CommandLine bevindt zich momenteel in PREVIEW en deze documentatie is voor versie 2.0 beta 5. Sommige informatie heeft betrekking op voorlopige versie van het product dat aanzienlijk kan worden gewijzigd voordat het wordt vrijgegeven. Microsoft geeft geen garanties, uitdrukkelijk of impliciet, met betrekking tot de informatie die hier wordt verstrekt.

System.CommandLine biedt een duidelijke scheiding tussen het parseren van de opdrachtregel en het aanroepen van acties. Het parseringsproces is verantwoordelijk voor het parseren van opdrachtregelinvoer en het maken van een System.CommandLine.ParseResult object dat de geparseerde waarden (en parseringsfouten) bevat. Het actie-aanroepproces is verantwoordelijk voor het aanroepen van de actie die is gekoppeld aan de geparseerde opdracht, optie of instructie (argumenten kunnen geen acties hebben).

In het volgende voorbeeld uit de Aan de slag met System.CommandLine zelfstudie wordt de ParseResult gemaakt door de opdrachtregelinvoer te parseren. Er worden geen acties gedefinieerd of aangeroepen:

using System.CommandLine;
using System.CommandLine.Parsing;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "The file to read and display on the console."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");
        rootCommand.Options.Add(fileOption);

        ParseResult parseResult = rootCommand.Parse(args);
        if (parseResult.GetValue(fileOption) is FileInfo parsedFile)
        {
            ReadFile(parsedFile);
            return 0;
        }
        foreach (ParseError parseError in parseResult.Errors)
        {
            Console.Error.WriteLine(parseError.Message);
        }
        return 1;
    }

    static void ReadFile(FileInfo file)
    {
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
        }
    }
}

Er wordt een actie aangeroepen wanneer een bepaalde opdracht (of instructie of optie) is geparseerd. De actie is een gemachtigde die een System.CommandLine.ParseResult parameter neemt en een int afsluitcode retourneert (asynchrone acties zijn ook beschikbaar)). De afsluitcode wordt geretourneerd door de System.CommandLine.Parsing.ParseResult.Invoke methode en kan worden gebruikt om aan te geven of de opdracht is uitgevoerd of niet.

In het volgende voorbeeld uit de zelfstudie Aan de slag met System.CommandLine de zelfstudie wordt de actie gedefinieerd voor de hoofdopdracht en aangeroepen na het parseren van de opdrachtregelinvoer:

using System.CommandLine;

namespace scl;

class Program
{
    static int Main(string[] args)
    {
        Option<FileInfo> fileOption = new("--file")
        {
            Description = "The file to read and display on the console."
        };

        RootCommand rootCommand = new("Sample app for System.CommandLine");
        rootCommand.Options.Add(fileOption);

        rootCommand.SetAction(parseResult =>
        {
            FileInfo parsedFile = parseResult.GetValue(fileOption);
            ReadFile(parsedFile);
            return 0;
        });

        ParseResult parseResult = rootCommand.Parse(args);
        return parseResult.Invoke();
    }

    static void ReadFile(FileInfo file)
    {
        foreach (string line in File.ReadLines(file.FullName))
        {
            Console.WriteLine(line);
        }
    }
}

Sommige ingebouwde symbolen, zoals System.CommandLine.Help.HelpOption, System.CommandLine.VersionOptionof System.CommandLine.Completions.SuggestDirective, worden geleverd met vooraf gedefinieerde acties. Deze symbolen worden automatisch toegevoegd aan de hoofdopdracht wanneer u deze maakt en wanneer u de aanroept System.CommandLine.Parsing.ParseResult, werken ze gewoon. Met behulp van acties kunt u zich richten op uw app-logica, terwijl de bibliotheek zorgt voor het parseren en aanroepen van acties voor ingebouwde symbolen. Als u wilt, kunt u zich aan het parseringsproces houden en geen acties definiëren (zoals in het eerste voorbeeld hierboven).

ParseResultaat

Het System.CommandLine.Parsing.ParseResult type is een klasse die de resultaten vertegenwoordigt van het parseren van de opdrachtregelinvoer. U moet deze gebruiken om de geparseerde waarden voor opties en argumenten op te halen (ongeacht of u acties gebruikt of niet). U kunt ook controleren of er parseringsfouten of niet-overeenkomende tokens zijn.

WaardeOphalen

Met System.CommandLine.Parsing.ParseResult.GetValue<T> de methode kunt u de waarden van opties en argumenten ophalen:

int integer = parseResult.GetValue(delayOption);
string? message = parseResult.GetValue(messageOption);

U kunt ook waarden op naam ophalen, maar hiervoor moet u het type waarde opgeven dat u wilt ophalen.

In het volgende voorbeeld worden initialisatieprogramma's voor C#-verzamelingen gebruikt om een hoofdopdracht te maken:

RootCommand rootCommand = new("Parameter binding example")
{
    new Option<int>("--delay")
    {
        Description = "An option whose argument is parsed as an int."
    },
    new Option<string>("--message")
    {
        Description = "An option whose argument is parsed as a string."
    }
};

Vervolgens wordt de GetValue methode gebruikt om de waarden op naam op te halen:

rootCommand.SetAction(parseResult =>
{
    int integer = parseResult.GetValue<int>("--delay");
    string? message = parseResult.GetValue<string>("--message");

    DisplayIntAndString(integer, message);
});

Deze overbelasting van GetValue krijgt de geparseerde of standaardwaarde voor de opgegeven symboolnaam, in de context van de geparseerde opdracht (niet de hele symboolstructuur). De naam van het symbool wordt geaccepteerd, geen alias.

Parseerfouten

De System.CommandLine.Parsing.ParseResult.Errors eigenschap bevat een lijst met parseringsfouten die zijn opgetreden tijdens het parseringsproces. Elke fout wordt vertegenwoordigd door een System.CommandLine.Parsing.ParseError object, dat informatie over de fout bevat, zoals het foutbericht en het token dat de fout heeft veroorzaakt.

Wanneer u de System.CommandLine.Parsing.ParseResult.Invoke methode aanroept, wordt er een afsluitcode geretourneerd die aangeeft of de parsering is geslaagd of niet. Als er parseringsfouten zijn, is de afsluitcode niet nul en worden alle parseringsfouten afgedrukt naar de standaardfout.

Als u de System.CommandLine.Parsing.ParseResult.Invoke methode niet aanroept, moet u de fouten zelf afhandelen, bijvoorbeeld door ze af te drukken:

foreach (ParseError parseError in parseResult.Errors)
{
    Console.Error.WriteLine(parseError.Message);
}
return 1;

Niet-overeenkomende tokens

De System.CommandLine.Parsing.ParseResult.UnmatchedTokens eigenschap bevat een lijst met de tokens die zijn geparseerd, maar die niet overeenkomen met een geconfigureerde opdracht, optie of argument.

De lijst met niet-overeenkomende tokens is handig in opdrachten die zich gedragen als wrappers. Een wrapper-opdracht gebruikt een set tokens en stuurt deze door naar een andere opdracht of app. De sudo opdracht in Linux is een voorbeeld. Het vereist de naam van een gebruiker om te imiteren, gevolgd door een uit te voeren opdracht. Voorbeeld:

sudo -u admin apt update

Met deze commandoregel wordt de apt update opdracht uitgevoerd door de gebruiker admin.

Als u een wrapper-opdracht zoals deze wilt implementeren, stelt u de opdrachteigenschap System.CommandLine.Command.TreatUnmatchedTokensAsErrors in op false. Vervolgens bevat de System.CommandLine.Parsing.ParseResult.UnmatchedTokens eigenschap alle argumenten die niet expliciet deel uitmaken van de opdracht. In het voorgaande voorbeeld ParseResult.UnmatchedTokens zouden de apt en update tokens worden opgenomen.

Acties

Acties zijn gemachtigden die worden aangeroepen wanneer een opdracht (of een optie of richtlijn) wordt geparseerd. Ze nemen een System.CommandLine.ParseResult parameter en retourneren een int (of Task<int>) afsluitcode. De afsluitcode wordt gebruikt om aan te geven of de actie is uitgevoerd of niet.

System.CommandLine biedt een abstracte basisklasse System.CommandLine.CommandLineAction en twee afgeleide klassen: System.CommandLine.SynchronousCommandLineAction en System.CommandLine.AsynchronousCommandLineAction. De vorige wordt gebruikt voor synchrone acties die een int afsluitcode retourneren, terwijl de laatste wordt gebruikt voor asynchrone acties die een Task<int> afsluitcode retourneren.

U hoeft geen afgeleid type te maken om een actie te definiëren. U kunt de System.CommandLine.Command.SetAction methode gebruiken om een actie voor een opdracht in te stellen. De synchrone actie kan een gemachtigde zijn die een System.CommandLine.ParseResult parameter neemt en een int afsluitcode retourneert. De asynchrone actie kan een delegate zijn die parameters System.CommandLine.ParseResult en CancellationToken accepteert en een Task<int> retourneert.

rootCommand.SetAction(parseResult =>
{
    FileInfo parsedFile = parseResult.GetValue(fileOption);
    ReadFile(parsedFile);
    return 0;
});

Asynchrone acties

Synchrone en asynchrone acties mogen niet worden gemengd in dezelfde toepassing. Als u asynchrone acties wilt gebruiken, moet uw toepassing asynchroon zijn van boven naar beneden. Dit betekent dat alle acties asynchroon moeten zijn en u de System.CommandLine.Command.SetAction methode moet gebruiken die een gemachtigde accepteert die een Task<int> afsluitcode retourneert. Bovendien moet de CancellationToken die wordt doorgegeven aan de gedelegeerde actie verder worden doorgegeven aan alle methoden die kunnen worden geannuleerd, zoals I/O-bewerkingen van bestanden of netwerkaanvragen.

Bovendien moet u ervoor zorgen dat de System.CommandLine.Parsing.ParseResult.InvokeAsync methode wordt gebruikt in plaats van System.CommandLine.Parsing.ParseResult.Invoke. Deze methode is asynchroon en retourneert een Task<int> afsluitcode. Het accepteert ook een optionele CancellationToken parameter die kan worden gebruikt om de actie te annuleren.

De voorgaande code maakt gebruik van een SetAction overloaden die een ParseResult krijgt in plaats van alleen CancellationToken met een ParseResult.

static Task<int> Main(string[] args)
{
    Option<string> urlOption = new("--url", "A URL.");
    RootCommand rootCommand = new("Handle termination example") { urlOption };

    rootCommand.SetAction((ParseResult parseResult, CancellationToken cancellationToken) =>
    {
        string? urlOptionValue = parseResult.GetValue(urlOption);
        return DoRootCommand(urlOptionValue, cancellationToken);
    });

    return rootCommand.Parse(args).InvokeAsync();
}

public static async Task<int> DoRootCommand(
    string? urlOptionValue, CancellationToken cancellationToken)
{
    using HttpClient httpClient = new();

    try
    {
        await httpClient.GetAsync(urlOptionValue, cancellationToken);
        return 0;
    }
    catch (OperationCanceledException)
    {
        await Console.Error.WriteLineAsync("The operation was aborted");
        return 1;
    }
}

Time-out voor procesbeëindiging

System.CommandLine.CommandLineConfiguration.ProcessTerminationTimeout maakt signalering en verwerking van procesbeëindiging (Ctrl+C, SIGINT, SIGTERM) mogelijk via een CancellationToken die wordt doorgegeven aan elke asynchrone actie tijdens het aanroepen. Het is standaard ingeschakeld (2 seconden), maar u kunt het instellen op null om het uit te schakelen.

Als de actie niet binnen de opgegeven time-out wordt voltooid, wordt het proces beëindigd wanneer deze is ingeschakeld. Dit is handig voor het afhandelen van de beëindiging, bijvoorbeeld door de status op te slaan voordat het proces wordt beëindigd.

Als u de voorbeeldcode uit de vorige alinea wilt testen, voert u de opdracht uit met een URL die even duurt voordat het laden is voltooid, drukt u op Ctrl+C. Druk op macOS op Command+Period(.). Voorbeeld:

testapp --url https://learn.microsoft.com/aspnet/core/fundamentals/minimal-apis

The operation was aborted

Afsluitcodes

De afsluitcode is een geheel getal dat wordt geretourneerd door een actie die aangeeft dat deze is geslaagd of mislukt. Volgens de conventie geeft een afsluitcode van 0 geslaagde aanmeldingen aan, terwijl een waarde die niet nul is, een fout aangeeft. Het is belangrijk om zinvolle afsluitcodes in uw toepassing te definiëren om duidelijk de status van de uitvoering van de opdracht te communiceren.

Elke SetAction methode heeft een overbelasting die een gemachtigde accepteert die een int afsluitcode retourneert waarbij de afsluitcode expliciet moet worden opgegeven en een overbelasting die retourneert 0.

static int Main(string[] args)
{
    Option<int> delayOption = new("--delay");
    Option<string> messageOption = new("--message");

    RootCommand rootCommand = new("Parameter binding example")
    {
        delayOption,
        messageOption
    };

    rootCommand.SetAction(parseResult =>
    {
        Console.WriteLine($"--delay = {parseResult.GetValue(delayOption)}");
        Console.WriteLine($"--message = {parseResult.GetValue(messageOption)}");
        // Value returned from the action delegate is the exit code.
        return 100;
    });

    return rootCommand.Parse(args).Invoke();
}

Zie ook

Hoe je parseren en valideren kunt aanpassen in System.CommandLine System.CommandLine overzicht