Cara menggunakan middleware di System.CommandLine

Artikel ini menjelaskan cara bekerja dengan middleware di aplikasi baris perintah yang dibangun dengan pustaka System.CommandLine. Penggunaan middleware adalah topik lanjutan yang tidak perlu dipertimbangkan oleh sebagian besar pengguna System.CommandLine.

Pengantar middleware

Meskipun setiap perintah memiliki handler yang akan dirutekan oleh System.CommandLine berdasarkan input, terdapat juga mekanisme untuk melakukan sirkuit pendek atau mengubah input sebelum logika aplikasi Anda dipanggil. Di antara penguraian dan pemanggilan, terdapat rantai tanggung jawab, yang dapat Anda sesuaikan. Sejumlah fitur bawaan System.CommandLine memanfaatkan kemampuan ini. Inilah cara sirkuit pendek opsi --help dan --version memanggil ke handler Anda.

Setiap panggilan dalam alur dapat mengambil tindakan berdasarkan ParseResult dan kembali lebih awal, atau memilih untuk memanggil item berikutnya dalam alur. Bahkan ParseResult dapat diganti selama fase ini. Panggilan terakhir dalam rantai adalah handler untuk perintah yang ditentukan.

Menambahkan ke alur middleware

Anda dapat menambahkan panggilan ke alur ini dengan memanggil CommandLineBuilderExtensions.AddMiddleware. Berikut adalah contoh kode yang memungkinkan direktif kustom. Setelah membuat perintah root bernama rootCommand, kode seperti biasa menambahkan opsi, argumen, dan handler. Kemudian middleware ditambahkan:

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

Dalam kode sebelumnya, middleware menulis "Hai!" jika direktif [just-say-hi] ditemukan dalam hasil penguraian. Ketika ini terjadi, handler normal perintah tidak dipanggil. Ia tidak dipanggil karena middleware tidak memanggil delegasi next.

Dalam contoh, context adalah InvocationContext, struktur database tunggal yang bertindak sebagai "akar" dari seluruh proses penanganan perintah. Ini adalah struktur yang paling kuat dalam System.CommandLine, dalam hal kemampuan. Terdapat dua kegunaan utama baginya di middleware:

• Ia menyediakan akses ke BindingContext, Parser, Console, dan HelpBuilder untuk mengambil dependensi yang diperlukan middleware untuk logika kustomnya.
• Anda dapat mengatur properti InvocationResult atau ExitCode untuk mengakhiri pemrosesan perintah dengan cara sirkuit pendek. Contohnya adalah opsi --help, yang diimplementasikan dengan cara ini.

Berikut adalah program lengkapnya, termasuk direktif using yang diperlukan.

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

Berikut adalah contoh baris perintah dan output yang dihasilkan dari kode sebelumnya:

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

Hi!

Lihat juga

System.CommandLine ringkasan