Parancsok, beállítások és argumentumok definiálása a következő helyen: System.CommandLine

Ez a cikk bemutatja, hogyan definiálhat parancsokat, beállításokat és argumentumokat a System.CommandLine kódtárral létrehozott parancssori alkalmazásokban. Az alábbi technikákat szemléltető teljes alkalmazás létrehozásához tekintse meg az Első lépések című oktatóanyagotSystem.CommandLine.

A parancssori alkalmazások parancsainak, beállításainak és argumentumainak tervezéséhez a tervezési útmutatóban talál útmutatást.

Gyökérparancs definiálása

Minden parancssori alkalmazás rendelkezik egy gyökérparancsot, amely a végrehajtható fájlra hivatkozik. A kód meghívásának legegyszerűbb esete, ha alparancsokat, beállításokat vagy argumentumokat nem tartalmazó alkalmazással rendelkezik, a következőhöz hasonlóan nézne ki:

using System.CommandLine;

class Program
{
    static async Task Main(string[] args)
    {
        var rootCommand = new RootCommand("Sample command-line app");

        rootCommand.SetHandler(() =>
        {
            Console.WriteLine("Hello world!");
        });

        await rootCommand.InvokeAsync(args);
    }
}

Alparancsok definiálása

A parancsok lehetnek gyermekparancsok, más néven alparancsok vagy igék, és tetszőleges számú szintet ágyazhatnak be. Az alábbi példában látható módon adhat hozzá alparancsokat:

var rootCommand = new RootCommand();
var sub1Command = new Command("sub1", "First-level subcommand");
rootCommand.Add(sub1Command);
var sub1aCommand = new Command("sub1a", "Second level subcommand");
sub1Command.Add(sub1aCommand);

A példában szereplő legbelső alparancs a következőképpen hívható meg:

myapp sub1 sub1a

Beállítások megadása

A parancskezelő metódus általában paraméterekkel rendelkezik, és az értékek parancssori beállításokból származhatnak. Az alábbi példa két lehetőséget hoz létre, és hozzáadja őket a gyökérparancshoz. A beállításnevek kettős kötőjel előtagokat tartalmaznak, amelyek a POSIX CLI-kre jellemzőek. A parancskezelő kódja megjeleníti a beállítások értékeit:

var delayOption = new Option<int>
    (name: "--delay",
    description: "An option whose argument is parsed as an int.",
    getDefaultValue: () => 42);
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

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

rootCommand.SetHandler((delayOptionValue, messageOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
        Console.WriteLine($"--message = {messageOptionValue}");
    },
    delayOption, messageOption);

Íme egy példa a parancssori bemenetre és az előző példakód eredményére:

myapp --delay 21 --message "Hello world!"

--delay = 21
--message = Hello world!

Globális beállítások

Ha egyszerre egy parancshoz szeretne hozzáadni egy lehetőséget, használja az Add előző példában látható módszert vagy AddOption metódust. Ha egy parancshoz szeretne hozzáadni egy lehetőséget, és rekurzív módon szeretné hozzáadni az összes alparancsot, használja a AddGlobalOption metódust, ahogyan az az alábbi példában látható:

var delayOption = new Option<int>
    ("--delay", "An option whose argument is parsed as an int.");
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.AddGlobalOption(delayOption);
rootCommand.Add(messageOption);

var subCommand1 = new Command("sub1", "First level subcommand");
rootCommand.Add(subCommand1);

var subCommand1a = new Command("sub1a", "Second level subcommand");
subCommand1.Add(subCommand1a);

subCommand1a.SetHandler((delayOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
    },
    delayOption);

await rootCommand.InvokeAsync(args);

Az előző kód globális beállításként hozzáadja --delay a gyökérparancsot, és elérhető a kezelőben a következőhöz subCommand1a: .

Argumentumok definiálása

Az argumentumok definiálva vannak, és hozzáadódnak a parancsokhoz, például a beállításokhoz. Az alábbi példa hasonló a beállítási példához, de a beállítások helyett argumentumokat határoz meg:

var delayArgument = new Argument<int>
    (name: "delay",
    description: "An argument that is parsed as an int.",
    getDefaultValue: () => 42);
var messageArgument = new Argument<string>
    ("message", "An argument that is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.Add(delayArgument);
rootCommand.Add(messageArgument);

rootCommand.SetHandler((delayArgumentValue, messageArgumentValue) =>
    {
        Console.WriteLine($"<delay> argument = {delayArgumentValue}");
        Console.WriteLine($"<message> argument = {messageArgumentValue}");
    },
    delayArgument, messageArgument);

await rootCommand.InvokeAsync(args);

Íme egy példa a parancssori bemenetre és az előző példakód eredményére:

myapp 42 "Hello world!"

<delay> argument = 42
<message> argument = Hello world!

Az alapértelmezett érték nélkül definiált argumentumot, például messageArgument az előző példában, kötelező argumentumként kezeli a rendszer. Megjelenik egy hibaüzenet, és a parancskezelő nem lesz meghívva, ha nincs megadva egy kötelező argumentum.

Aliasok definiálása

A parancsok és a beállítások is támogatják az aliasokat. Aliast a következő hívással AddAliasadhat hozzá egy beállításhoz:

var option = new Option("--framework");
option.AddAlias("-f");

Ezen alias alapján a következő parancssorok egyenértékűek:

myapp -f net6.0
myapp --framework net6.0

A parancs aliasai ugyanúgy működnek.

var command = new Command("serialize");
command.AddAlias("serialise");

Ez a kód egyenértékűvé teszi a következő parancssorokat:

myapp serialize
myapp serialise

Javasoljuk, hogy minimalizálja a definiált beállítási aliasok számát, és kerülje bizonyos aliasok definiálását. További információ: Rövid formátumú aliasok.

Kötelező beállítások

Ha kötelezővé szeretne tenni egy beállítást, állítsa a tulajdonságát IsRequiredtruea következő példában látható módon:

var endpointOption = new Option<Uri>("--endpoint") { IsRequired = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

A parancs beállításainak szakasza jelzi, hogy a beállítás szükséges:

Options:
  --endpoint <uri> (REQUIRED)
  --version               Show version information
  -?, -h, --help          Show help and usage information

Ha a példaalkalmazás parancssora nem tartalmaz --endpoint, hibaüzenet jelenik meg, és a parancskezelő nem lesz meghívva:

Option '--endpoint' is required.

Ha egy kötelező beállítás alapértelmezett értékkel rendelkezik, a beállítást nem kell megadni a parancssorban. Ebben az esetben az alapértelmezett érték adja meg a szükséges beállításértéket.

Rejtett parancsok, beállítások és argumentumok

Előfordulhat, hogy támogatni szeretne egy parancsot, beállítást vagy argumentumot, de ne tegye könnyen felderíthetővé. Előfordulhat például, hogy elavult, rendszergazdai vagy előzetes verziójú szolgáltatás. A tulajdonsággal megakadályozhatja, hogy a IsHidden felhasználók tabulátorkiegészítéssel vagy súgóval felfedezzék ezeket a funkciókat, ahogyan az alábbi példában látható:

var endpointOption = new Option<Uri>("--endpoint") { IsHidden = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

A példa parancsának beállítások szakasza segít kihagyni a --endpoint lehetőséget.

Options:
  --version               Show version information
  -?, -h, --help          Show help and usage information

Argumentum-aritás beállítása

A tulajdonság használatával explicit módon állíthatja be az Arity argumentum-aritást, de a legtöbb esetben ez nem szükséges. System.CommandLine automatikusan meghatározza az argumentum-aritást az argumentumtípus alapján:

Több argumentum

Ha parancsot hív meg, alapértelmezés szerint megismételhet egy beállításnevet, hogy több argumentumot adjon meg egynél nagyobb aritású beállításhoz.

myapp --items one --items two --items three

Ha több argumentumot szeretne engedélyezni a beállításnév megismétlése nélkül, állítsa a következőre Option.AllowMultipleArgumentsPerTokentrue: . Ezzel a beállítással a következő parancssort adhatja meg.

myapp --items one two three

Ugyanez a beállítás eltérő hatással van, ha a maximális argumentum-aritás 1. Lehetővé teszi egy lehetőség ismétlését, de csak az utolsó értéket veszi fel a sorban. Az alábbi példában az érték three az alkalmazásnak lesz átadva.

myapp --item one --item two --item three

Érvényes argumentumértékek listázása

Ha meg szeretné adni egy beállítás vagy argumentum érvényes értékeinek listáját, adjon meg egy enumerát a beállítás típusaként vagy használataként FromAmong, az alábbi példában látható módon:

var languageOption = new Option<string>(
    "--language",
    "An option that that must be one of the values of a static list.")
        .FromAmong(
            "csharp",
            "fsharp",
            "vb",
            "pwsh",
            "sql");

Íme egy példa a parancssori bemenetre és az előző példakód eredményére:

myapp --language not-a-language

Argument 'not-a-language' not recognized. Must be one of:
        'csharp'
        'fsharp'
        'vb'
        'pwsh'
        'sql'

A parancs beállítások szakasza az érvényes értékeket mutatja:

Options:
  --language <csharp|fsharp|vb|pwsh|sql>  An option that must be one of the values of a static list.
  --version                               Show version information
  -?, -h, --help                          Show help and usage information

Beállítás- és argumentumérvényesítés

Az argumentumérvényesítésről és annak testreszabásáról a paraméterkötésről szóló cikk alábbi szakaszaiban talál további információt:

• Beépített típus- és aritásargumentum-ellenőrzés
• Egyéni ellenőrzés és kötés

Lásd még

• System.CommandLine Áttekintés
• Paraméterkötés