Middleware gebruiken in System.CommandLine

Belangrijk

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

In dit artikel wordt uitgelegd hoe u met middleware kunt werken in opdrachtregel-apps die zijn gebouwd met de System.CommandLine bibliotheek. Het gebruik van middleware is een geavanceerd onderwerp dat de meeste System.CommandLine gebruikers niet hoeven te overwegen.

Inleiding tot middleware

Hoewel elke opdracht een handler heeft waarnaar System.CommandLine wordt gerouteerd op basis van invoer, is er ook een mechanisme voor kortsluiting of het wijzigen van de invoer voordat uw toepassingslogica wordt aangeroepen. Tussen parseren en aanroepen is er een keten van verantwoordelijkheid die u kunt aanpassen. Een aantal ingebouwde functies om System.CommandLine gebruik te maken van deze mogelijkheid. Dit is de manier waarop kortsluitingsoproepen --help--version naar uw handler worden aanroepen.

Elke aanroep in de pijplijn kan actie ondernemen op basis van het ParseResult en vroeg retourneren of ervoor kiezen om het volgende item in de pijplijn aan te roepen. De ParseResult kan zelfs tijdens deze fase worden vervangen. De laatste aanroep in de keten is de handler voor de opgegeven opdracht.

Toevoegen aan de middleware-pijplijn

U kunt een aanroep aan deze pijplijn toevoegen door aan te roepen CommandLineBuilderExtensions.AddMiddleware. Hier volgt een voorbeeld van code waarmee een aangepaste instructie mogelijk is. Nadat u een hoofdopdracht met de naam hebt gemaakt rootCommand, voegt de code zoals gebruikelijk opties, argumenten en handlers toe. Vervolgens wordt de middleware toegevoegd:

var commandLineBuilder = new CommandLineBuilder(rootCommand);

commandLineBuilder.AddMiddleware(async (context, next) =>
{
    if (context.ParseResult.Directives.Contains("just-say-hi"))
    {
        context.Console.WriteLine("Hi!");
    }
    else
    {
        await next(context);
    }
});

commandLineBuilder.UseDefaults();
var parser = commandLineBuilder.Build();
await parser.InvokeAsync(args);

In de voorgaande code schrijft de middleware 'Hi!' uit als de instructie [just-say-hi] wordt gevonden in het parseringsresultaat. Als dit gebeurt, wordt de normale handler van de opdracht niet aangeroepen. Deze wordt niet aangeroepen omdat de middleware de next gemachtigde niet aanroept.

In het voorbeeld is InvocationContexteen context singletonstructuur die fungeert als de 'root' van het hele proces voor het verwerken van opdrachten. Dit is de krachtigste structuur in System.CommandLinetermen van mogelijkheden. Er zijn twee belangrijke toepassingen voor het in middleware:

• Het biedt toegang tot de BindingContext, Parseren ConsoleHelpBuilder om afhankelijkheden op te halen die een middleware nodig heeft voor de aangepaste logica.
• U kunt de InvocationResult of ExitCode eigenschappen instellen om de verwerking van opdrachten op korte termijn te beëindigen. Een voorbeeld hiervan is de --help optie, die op deze manier wordt geïmplementeerd.

Hier volgt het volledige programma, inclusief vereiste using instructies.

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

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

        var rootCommand = new RootCommand("Middleware example");
        rootCommand.Add(delayOption);
        rootCommand.Add(messageOption);

        rootCommand.SetHandler((delayOptionValue, messageOptionValue) =>
            {
                DoRootCommand(delayOptionValue, messageOptionValue);
            },
            delayOption, messageOption);

        var commandLineBuilder = new CommandLineBuilder(rootCommand);

        commandLineBuilder.AddMiddleware(async (context, next) =>
        {
            if (context.ParseResult.Directives.Contains("just-say-hi"))
            {
                context.Console.WriteLine("Hi!");
            }
            else
            {
                await next(context);
            }
        });

        commandLineBuilder.UseDefaults();
        var parser = commandLineBuilder.Build();
        await parser.InvokeAsync(args);
    }

    public static void DoRootCommand(int delay, string message)
    {
        Console.WriteLine($"--delay = {delay}");
        Console.WriteLine($"--message = {message}");
    }
}

Hier volgt een voorbeeld van een opdrachtregel en resulterende uitvoer van de voorgaande code:

myapp [just-say-hi] --delay 42 --message "Hello world!"

Hi!

Zie ook

System.CommandLine Overzicht