Jak używać oprogramowania pośredniczącego w programie System.CommandLine

Ważne

System.CommandLine jest obecnie dostępna w wersji zapoznawczej, a ta dokumentacja dotyczy wersji 2.0 beta 4. Niektóre informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany przed jego wydaniem. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

W tym artykule wyjaśniono, jak pracować z oprogramowaniem pośredniczącym System.CommandLine w aplikacjach wiersza polecenia utworzonych za pomocą biblioteki. Korzystanie z oprogramowania pośredniczącego to zaawansowany temat, który większość System.CommandLine użytkowników nie musi brać pod uwagę.

Wprowadzenie do oprogramowania pośredniczącego

Chociaż każde polecenie zawiera procedurę obsługi, która System.CommandLine będzie kierować na podstawie danych wejściowych, istnieje również mechanizm zwarć lub zmiana danych wejściowych przed wywołaniem logiki aplikacji. Między analizowaniem i wywołaniem istnieje łańcuch odpowiedzialności, który można dostosować. Wiele wbudowanych funkcji System.CommandLine umożliwia korzystanie z tej funkcji. W ten sposób metody --help i --version opcje zwarć wywołania programu obsługi.

Każde wywołanie potoku może podjąć akcję na ParseResult podstawie wartości i zwracać wcześniej lub wybrać wywołanie następnego elementu w potoku. Element ParseResult można nawet zamienić w tej fazie. Ostatnie wywołanie w łańcuchu to procedura obsługi dla określonego polecenia.

Dodawanie do potoku oprogramowania pośredniczącego

Wywołanie tego potoku można dodać, wywołując metodę CommandLineBuilderExtensions.AddMiddleware. Oto przykład kodu, który umożliwia dyrektywę niestandardową. Po utworzeniu głównego polecenia o nazwie rootCommand, kod jak zwykle dodaje opcje, argumenty i procedury obsługi. Następnie zostanie dodane oprogramowanie pośredniczące:

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

W poprzednim kodzie oprogramowanie pośredniczące zapisuje "Hi!", jeśli dyrektywa [just-say-hi] zostanie znaleziona w wyniku analizy. W takim przypadku normalny program obsługi polecenia nie jest wywoływany. Nie jest wywoływany, ponieważ oprogramowanie pośredniczące nie wywołuje delegata next .

W tym przykładzie context jest InvocationContextto pojedyncza struktura, która działa jako "główny" całego procesu obsługi poleceń. Jest to najbardziej zaawansowana struktura w systemie pod System.CommandLinewzględem możliwości. Istnieją dwa główne zastosowania oprogramowania pośredniczącego:

• Zapewnia dostęp do BindingContextelementów , , ParserConsolei HelpBuilder do pobierania zależności, których oprogramowanie pośredniczące wymaga dla jego logiki niestandardowej.
• Właściwości lub ExitCode można ustawić InvocationResult w celu zakończenia przetwarzania poleceń w sposób zwarciowy. Przykładem jest --help opcja zaimplementowana w ten sposób.

Oto kompletny program, w tym wymagane using dyrektywy.

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

Oto przykładowy wiersz polecenia i wynikowe dane wyjściowe z poprzedniego kodu:

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

Hi!

Zobacz też

System.CommandLine Przegląd