Jak používat middleware v System.CommandLine

Důležité

System.CommandLine je aktuálně ve verzi PREVIEW a tato dokumentace je určená pro verzi 2.0 beta 4. Některé informace se týkají předběžné verze produktu, který může být podstatně změněn před vydáním. Microsoft neposkytuje žádné záruky, výslovné ani předpokládané, týkající se zde uváděných informací.

Tento článek vysvětluje, jak pracovat s middlewarem v aplikacích příkazového řádku vytvořených pomocí System.CommandLine knihovny. Použití middlewaru je pokročilé téma, které většina System.CommandLine uživatelů nebude muset zvážit.

Úvod do middlewaru

Zatímco každý příkaz má obslužnou rutinu, která System.CommandLine se bude směrovat na základě vstupu, existuje také mechanismus pro zkratování nebo změnu vstupu před vyvolání logiky aplikace. Mezi analýzou a vyvoláním existuje řetězec odpovědnosti, který si můžete přizpůsobit. Řadu integrovaných funkcí, které System.CommandLine tuto funkci využívají. Takto volání --help zkratek a --version možností obslužné rutiny.

Každé volání v kanálu může provést akci na ParseResult základě počátku a návratu nebo zvolit volání další položky v kanálu. V ParseResult této fázi lze dokonce nahradit. Posledním voláním v řetězci je obslužná rutina zadaného příkazu.

Přidání do kanálu middlewaru

Voláním můžete do tohoto kanálu přidat volání CommandLineBuilderExtensions.AddMiddleware. Tady je příklad kódu, který umožňuje vlastní direktivu. Po vytvoření kořenového příkazu s názvem rootCommandpřidá kód jako obvykle možnosti, argumenty a obslužné rutiny. Pak se přidá middleware:

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

V předchozím kódu middleware zapíše "Hi!" pokud je direktiva [just-say-hi] nalezena ve výsledku analýzy. Když k tomu dojde, není vyvolána normální obslužná rutina příkazu. Není vyvolána, protože middleware nevolá delegáta next .

V příkladu je InvocationContextsingleton struktura, context která funguje jako "kořen" celého procesu zpracování příkazů. Jedná se o nejvýkonnější strukturu z System.CommandLinehlediska schopností. V middlewaru se používají dva hlavní způsoby:

• Poskytuje přístup k objektu BindingContext, ParserConsolea HelpBuilder k načtení závislostí, které middleware vyžaduje pro vlastní logiku.
• Pokud chcete ukončit zpracování příkazů krátkým způsobem, můžete nastavit InvocationResult vlastnosti nebo ExitCode vlastnosti. Příkladem je --help možnost, která se tímto způsobem implementuje.

Tady je kompletní program, včetně povinných using direktiv.

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

Tady je příklad příkazového řádku a výsledný výstup z předchozího kódu:

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

Hi!

Viz také

System.CommandLine Přehled