Definiera kommandon, alternativ och argument i System.CommandLine

Den här artikeln beskriver hur du definierar kommandon, alternativ och argument i kommandoradsappar som skapas med System.CommandLine biblioteket. Information om hur du skapar ett komplett program som illustrerar dessa tekniker finns i självstudien Komma igång med System.CommandLine.

Vägledning om hur du utformar kommandon, alternativ och argument för en kommandoradsapp finns i Designvägledning.

Definiera ett rotkommando

Varje kommandoradsapp har ett rotkommando som refererar till själva den körbara filen. Det enklaste fallet för att anropa koden, om du har en app utan underkommandon, alternativ eller argument, skulle se ut så här:

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

Definiera underkommandon

Kommandon kan ha underordnade kommandon, så kallade underkommandon eller verb, och de kan kapsla så många nivåer som du behöver. Du kan lägga till underkommandon enligt följande exempel:

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

Den innersta underkommandot i det här exemplet kan anropas så här:

myapp sub1 sub1a

Definiera alternativ

En kommandohanterarmetod har vanligtvis parametrar och värdena kan komma från kommandoradsalternativ. I följande exempel skapas två alternativ och de läggs till i rotkommandot. Alternativnamnen innehåller prefix med dubbla bindestreck, vilket är typiskt för POSIX-CLIs. Kommandohanterarkoden visar värdena för dessa alternativ:

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

Här är ett exempel på kommandoradsindata och resulterande utdata för föregående exempelkod:

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

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

Globala alternativ

Om du vill lägga till ett alternativ i ett kommando i taget använder du Add metoden eller AddOption som du ser i föregående exempel. Om du vill lägga till ett alternativ i ett kommando och rekursivt till alla dess underkommandon AddGlobalOption använder du metoden enligt följande exempel:

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

Föregående kod lägger till --delay som ett globalt alternativ i rotkommandot och är tillgängligt i hanteraren för subCommand1a.

Definiera argument

Argument definieras och läggs till i kommandon som alternativ. Följande exempel är som alternativexemplet, men det definierar argument i stället för alternativ:

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

Här är ett exempel på kommandoradsindata och resulterande utdata för föregående exempelkod:

myapp 42 "Hello world!"

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

Ett argument som definieras utan ett standardvärde, till exempel messageArgument i föregående exempel, behandlas som ett obligatoriskt argument. Ett felmeddelande visas och kommandohanteraren anropas inte om ett obligatoriskt argument inte anges.

Definiera alias

Både kommandon och alternativ stöder alias. Du kan lägga till ett alias i ett alternativ genom att anropa AddAlias:

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

Med det här aliaset är följande kommandorader likvärdiga:

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

Kommandoalias fungerar på samma sätt.

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

Den här koden gör följande kommandorader likvärdiga:

myapp serialize
myapp serialise

Vi rekommenderar att du minimerar antalet alternativalias som du definierar och undviker att definiera vissa alias i synnerhet. Mer information finns i Kortformatsalias.

Obligatoriska alternativ

Om du vill göra ett alternativ obligatoriskt anger du dess IsRequired egenskap till true, som du ser i följande exempel:

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

Alternativavsnittet i kommandohjälpen anger att alternativet krävs:

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

Om kommandoraden för den här exempelappen inte innehåller --endpointvisas ett felmeddelande och kommandohanteraren anropas inte:

Option '--endpoint' is required.

Om ett obligatoriskt alternativ har ett standardvärde behöver alternativet inte anges på kommandoraden. I så fall ger standardvärdet det obligatoriska alternativvärdet.

Dolda kommandon, alternativ och argument

Du kanske vill ha stöd för ett kommando, alternativ eller argument, men undvik att göra det enkelt att identifiera. Det kan till exempel vara en inaktuell eller administrativ eller förhandsgranskningsfunktion. Använd egenskapen IsHidden för att förhindra användare från att identifiera sådana funktioner med hjälp av tabbavslut eller hjälp, som du ser i följande exempel:

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

Alternativavsnittet i det här exemplets kommando hjälper till att utelämna alternativet --endpoint .

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

Ange argumentaritet

Du kan uttryckligen ange argumentaritet med hjälp Arity av egenskapen, men i de flesta fall är det inte nödvändigt. System.CommandLine avgör automatiskt argumentariteten baserat på argumenttypen:

Flera argument

När du anropar ett kommando kan du som standard upprepa ett alternativnamn för att ange flera argument för ett alternativ som har maximal aritet som är större än ett.

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

Om du vill tillåta flera argument utan att upprepa alternativnamnet anger du Option.AllowMultipleArgumentsPerToken till true. Med den här inställningen kan du ange följande kommandorad.

myapp --items one two three

Samma inställning har en annan effekt om maximal argumentaritet är 1. Det gör att du kan upprepa ett alternativ men tar bara det sista värdet på raden. I följande exempel skickas värdet three till appen.

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

Visa en lista över giltiga argumentvärden

Om du vill ange en lista med giltiga värden för ett alternativ eller argument anger du en uppräkning som alternativtyp eller använder FromAmong, enligt följande exempel:

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

Här är ett exempel på kommandoradsindata och resulterande utdata för föregående exempelkod:

myapp --language not-a-language

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

Alternativavsnittet i kommandohjälpen visar giltiga värden:

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

Alternativ- och argumentverifiering

Information om argumentverifiering och hur du anpassar den finns i följande avsnitt i artikeln Parameterbindning :

• Inbyggd typ- och arity-argumentverifiering
• Anpassad validering och bindning

Se även

• System.CommandLine Översikt
• Parameterbindning