Delen via

Opdrachten, opties en argumenten definiëren in System.CommandLine

  • Artikel

Belangrijk

System.CommandLine bevindt zich momenteel in PREVIEW en deze documentatie is voor versie 2.0 beta 4. Sommige informatie heeft betrekking op voorlopige versie van het product dat aanzienlijk kan worden gewijzigd voordat het wordt vrijgegeven. Microsoft biedt geen enkele expliciete of impliciete garanties met betrekking tot de informatie die hier wordt verstrekt.

In dit artikel wordt uitgelegd hoe u opdrachten, opties en argumenten definieert in opdrachtregel-apps die zijn gebouwd met de System.CommandLine bibliotheek. Als u een volledige toepassing wilt bouwen die deze technieken illustreert, raadpleegt u de zelfstudie Aan de slag met System.CommandLine.

Zie Ontwerprichtlijnen voor hulp bij het ontwerpen van de opdrachten, opties en argumenten van een opdrachtregel-app.

Een hoofdopdracht definiëren

Elke opdrachtregel-app heeft een hoofdopdracht, die verwijst naar het uitvoerbare bestand zelf. Het eenvoudigste geval voor het aanroepen van uw code, als u een app zonder subopdrachten, opties of argumenten hebt, ziet er als volgt uit:

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

Subopdrachten definiëren

Opdrachten kunnen onderliggende opdrachten hebben, ook wel subopdrachten of werkwoorden genoemd, en ze kunnen zoveel niveaus nesten als u nodig hebt. U kunt subopdrachten toevoegen, zoals wordt weergegeven in het volgende voorbeeld:

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

De binnenste subopdracht in dit voorbeeld kan als volgt worden aangeroepen:

myapp sub1 sub1a

Opties definiëren

Een opdrachthandlermethode heeft doorgaans parameters en de waarden kunnen afkomstig zijn van opdrachtregelopties. In het volgende voorbeeld worden twee opties gemaakt en toegevoegd aan de hoofdopdracht. De optienamen bevatten voorvoegsels met dubbele afbreekstreepjes, wat gebruikelijk is voor POSIX CLIs. De opdrachthandlercode geeft de waarden van deze opties weer:

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

Hier volgt een voorbeeld van opdrachtregelinvoer en de resulterende uitvoer voor de voorgaande voorbeeldcode:

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

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

Algemene opties

Als u een optie aan één opdracht tegelijk wilt toevoegen, gebruikt u de Add of AddOption methode, zoals wordt weergegeven in het voorgaande voorbeeld. Als u een optie aan een opdracht wilt toevoegen en recursief wilt toevoegen aan alle subopdrachten, gebruikt u de AddGlobalOption methode, zoals wordt weergegeven in het volgende voorbeeld:

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

De voorgaande code wordt --delay toegevoegd als een globale optie aan de hoofdopdracht en is beschikbaar in de handler voor subCommand1a.

Argumenten definiëren

Argumenten worden gedefinieerd en toegevoegd aan opdrachten zoals opties. Het volgende voorbeeld lijkt op het voorbeeld met opties, maar definieert argumenten in plaats van opties:

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

Hier volgt een voorbeeld van opdrachtregelinvoer en de resulterende uitvoer voor de voorgaande voorbeeldcode:

myapp 42 "Hello world!"

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

Een argument dat is gedefinieerd zonder een standaardwaarde, zoals messageArgument in het voorgaande voorbeeld, wordt behandeld als een vereist argument. Er wordt een foutbericht weergegeven en de opdrachthandler wordt niet aangeroepen als er geen vereist argument is opgegeven.

Aliassen definiëren

Zowel opdrachten als opties ondersteunen aliassen. U kunt een alias toevoegen aan een optie door het aanroepen van AddAlias:

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

Op basis van deze alias zijn de volgende opdrachtregels equivalent:

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

Opdrachtaliassen werken op dezelfde manier.

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

Met deze code komen de volgende opdrachtregels overeen:

myapp serialize
myapp serialise

Het is raadzaam om het aantal optiealiassen dat u definieert te minimaliseren en om te voorkomen dat bepaalde aliassen in het bijzonder worden gedefinieerd. Zie Korte aliassen voor meer informatie.

Vereiste opties

Als u een optie vereist wilt maken, stelt u IsRequired de eigenschap truein op , zoals wordt weergegeven in het volgende voorbeeld:

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

In de sectie Opties van de Help-opdracht wordt aangegeven dat de optie is vereist:

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

Als de opdrachtregel voor deze voorbeeld-app niet bevat --endpoint, wordt er een foutbericht weergegeven en wordt de opdrachthandler niet aangeroepen:

Option '--endpoint' is required.

Als een vereiste optie een standaardwaarde heeft, hoeft de optie niet op de opdrachtregel te worden opgegeven. In dat geval biedt de standaardwaarde de vereiste optiewaarde.

Verborgen opdrachten, opties en argumenten

Mogelijk wilt u een opdracht, optie of argument ondersteunen, maar vermijdt u het gemakkelijk te detecteren. Het kan bijvoorbeeld een afgeschafte of beheer- of preview-functie zijn. Gebruik de IsHidden eigenschap om te voorkomen dat gebruikers dergelijke functies detecteren met behulp van tabvoltooiing of Help, zoals wordt weergegeven in het volgende voorbeeld:

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

In de sectie met opties van de opdracht van dit voorbeeld wordt de --endpoint optie weggelaten.

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

Argument arity instellen

U kunt expliciet argument arity instellen met behulp van de eigenschap, maar in de Arity meeste gevallen is dat niet nodig. System.CommandLine bepaalt automatisch de argument arity op basis van het argumenttype:

Argumenttype Standaard arity
Boolean ArgumentArity.ZeroOrOne
Verzamelingstypen ArgumentArity.ZeroOrMore
Alles ArgumentArity.ExactlyOne

Meerdere argumenten

Wanneer u een opdracht aanroept, kunt u standaard een optienaam herhalen om meerdere argumenten op te geven voor een optie met een maximale arity groter dan één.

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

Als u meerdere argumenten wilt toestaan zonder de optienaam te herhalen, stelt u deze in Option.AllowMultipleArgumentsPerToken op true. Met deze instelling kunt u de volgende opdrachtregel invoeren.

myapp --items one two three

Dezelfde instelling heeft een ander effect als het maximumargument 1 is. Hiermee kunt u een optie herhalen, maar alleen de laatste waarde op de regel gebruiken. In het volgende voorbeeld wordt de waarde three doorgegeven aan de app.

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

Geldige argumentwaarden weergeven

Als u een lijst met geldige waarden voor een optie of argument wilt opgeven, geeft u een opsomming op als het optietype of het gebruik FromAmong, zoals wordt weergegeven in het volgende voorbeeld:

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

Hier volgt een voorbeeld van opdrachtregelinvoer en de resulterende uitvoer voor de voorgaande voorbeeldcode:

myapp --language not-a-language

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

In de sectie Opties van de Help van de opdracht worden de geldige waarden weergegeven:

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

Validatie van opties en argumenten

Zie de volgende secties in het artikel Parameterbinding voor informatie over argumentvalidatie en het aanpassen ervan:

Zie ook