Delen via

Overzicht van syntaxis: Opdrachten, opties en argumenten

In dit artikel wordt de syntaxis voor de opdrachtregel uitgelegd die System.CommandLine herkent. De informatie is nuttig voor zowel gebruikers als ontwikkelaars van .NET-opdrachtregel-apps, waaronder de .NET CLI.

Symbolen

System.CommandLine Parseert opdrachtregelinvoer in tokens, die tekenreeksen zijn gescheiden door spaties. Denk bijvoorbeeld aan de volgende opdrachtregel:

dotnet tool install dotnet-suggest --global --verbosity quiet

Deze invoer wordt door de dotnet toepassing geparseerd in tokenstool, , installdotnet-suggest, , --global, --verbosityen quiet.

Tokens worden geïnterpreteerd als opdrachten, opties of argumenten. Het opdrachtregelprogramma dat wordt aangeroepen, bepaalt hoe de tokens na de eerste worden geïnterpreteerd. In de volgende tabel ziet u hoe System.CommandLine het voorgaande voorbeeld wordt geïnterpreteerd:

Teken Geparseerd als
tool Subopdracht
install Subopdracht
dotnet-suggest Argument voor installatieopdracht
--global Optie voor installatieopdracht
--verbosity Optie voor installatieopdracht
quiet Argument voor --verbosity optie

Een token kan spaties bevatten als het tussen aanhalingstekens (") staat. Hier volgt een voorbeeld:

dotnet tool search "ef migrations add"

De symboolhiërarchie (opdrachten, opties, argumenten) wordt beschouwd als vertrouwde invoer; de tokenwaarden zijn niet.

Opdrachten

Een opdracht in opdrachtregelinvoer is een token dat een actie aangeeft of een groep gerelateerde acties definieert. Voorbeeld:

  • In dotnet run, run is een opdracht waarmee een actie wordt opgegeven.
  • In dotnet tool install is install een opdracht die een actie specificeert, en tool is een opdracht die een groep gerelateerde opdrachten specificeert. Er zijn andere hulpprogramma-gerelateerde opdrachten, zoals tool uninstall, tool listen tool update.

Hoofdopdracht

De hoofdopdracht is de opdracht die de naam van het uitvoerbare bestand van de app opgeeft. Met de dotnet opdracht wordt bijvoorbeeld het uitvoerbare dotnet.exe opgegeven.

Command is de klasse algemeen voor elke opdracht of subopdracht, terwijl RootCommand dit een gespecialiseerde versie is die is bedoeld voor het hoofdinvoerpunt van de toepassing. RootCommand neemt alle functies over van Command maar voegt hoofdspecifiek gedrag en standaardwaarden toe, zoals help-optie, versieoptie en richtlijn voorstellen.

Subopdrachten

De meeste opdrachtregel-apps ondersteunen subopdrachten, ook wel werkwoorden genoemd. De dotnet opdracht heeft bijvoorbeeld een run subopdracht die u aanroept door in te voeren dotnet run.

Subopdrachten kunnen hun eigen subopdrachten hebben. In dotnet tool install, install is een subopdracht van tool.

U kunt subopdrachten toevoegen, zoals wordt weergegeven in het volgende voorbeeld:

RootCommand rootCommand = new();

Command sub1Command = new("sub1", "First-level subcommand");
rootCommand.Subcommands.Add(sub1Command);

Command sub1aCommand = new("sub1a", "Second level subcommand");
sub1Command.Subcommands.Add(sub1aCommand);

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

myapp sub1 sub1a

Opties

Een optie is een benoemde parameter die kan worden doorgegeven aan een opdracht. POSIX CLI's gebruiken doorgaans de optienaam met twee streepjes (--). In het volgende voorbeeld ziet u twee opties:

dotnet tool update dotnet-suggest --verbosity quiet --global
                                  ^---------^       ^------^

Zoals in dit voorbeeld wordt geïllustreerd, kan de waarde van de optie expliciet (quietvoor--verbosity) of impliciet zijn (niets volgt).--global Opties waarvoor geen waarde is opgegeven, zijn doorgaans Booleaanse parameters die standaard true worden ingesteld als de optie is opgegeven op de opdrachtregel.

Voor sommige Windows-opdrachtregel-apps identificeert u een optie met behulp van een voorloopslash (/) met de naam van de optie. Voorbeeld:

msbuild /version
        ^------^

System.CommandLine ondersteunt zowel POSIX- als Windows-voorvoegselconventies.

Wanneer u een optie configureert, geeft u de naam van de optie op, inclusief het voorvoegsel:

Option<int> delayOption = new("--delay", "-d")
{
    Description = "An option whose argument is parsed as an int.",
    DefaultValueFactory = parseResult => 42,
};
Option<string> messageOption = new("--message", "-m")
{
    Description = "An option whose argument is parsed as a string."
};

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

Als u een optie aan een opdracht wilt toevoegen en recursief wilt toevoegen aan alle subopdrachten, gebruikt u de System.CommandLine.Symbol.Recursive eigenschap.

Vereiste opties

Sommige opties hebben vereiste argumenten. Bijvoorbeeld, in de .NET CLI is een mapnaamargument --output vereist. Als het argument niet is opgegeven, mislukt de opdracht. Om een optie vereiste te maken, stelt u de eigenschap Required op true, zoals wordt weergegeven in het volgende voorbeeld:

Option<FileInfo> fileOption = new("--output")
{
    Required = true
};

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

Argumenten

Een argument is een niet-benoemde parameter die kan worden doorgegeven aan een opdracht. In het volgende voorbeeld ziet u een argument voor de build opdracht.

dotnet build myapp.csproj
             ^----------^

Wanneer u een argument configureert, geeft u de naam van het argument op (deze wordt niet gebruikt voor parseren, maar kan worden gebruikt om geparseerde waarden op naam of help weer te geven) en typt u:

Argument<int> delayArgument = new("delay")
{
    Description = "An argument that is parsed as an int.",
    DefaultValueFactory = parseResult => 42
};
Argument<string> messageArgument = new("message")
{
    Description = "An argument that is parsed as a string."
};

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

Standaardwaarden

Zowel argumenten als opties kunnen standaardwaarden hebben die van toepassing zijn als er expliciet geen argument wordt opgegeven. Veel opties zijn bijvoorbeeld impliciet Booleaanse parameters met een standaardwaarde van true wanneer de optienaam in de opdrachtregel staat. De volgende opdrachtregelvoorbeelden zijn gelijkwaardig:

dotnet tool update dotnet-suggest --global
                                  ^------^

dotnet tool update dotnet-suggest --global true
                                  ^-----------^

Een argument dat zonder standaardwaarde is gedefinieerd, wordt behandeld als een vereist argument.

Parseerfouten

Opties en argumenten hebben verwachte typen en er wordt een fout gegenereerd wanneer de waarde niet kan worden geparseerd. De volgende opdrachtfouten zijn bijvoorbeeld omdat 'stil' niet een van de geldige waarden is voor --verbosity:

dotnet build --verbosity silent

Option<string> verbosityOption = new("--verbosity", "-v")
{
    Description = "Set the verbosity level.",
};
verbosityOption.AcceptOnlyFromAmong("quiet", "minimal", "normal", "detailed", "diagnostic");
RootCommand rootCommand = new() { verbosityOption };

ParseResult parseResult = rootCommand.Parse(args);
foreach (ParseError parseError in parseResult.Errors)
{
    Console.WriteLine(parseError.Message);
}

Argument 'silent' not recognized. Must be one of:
        'quiet'
        'minimal'
        'normal'
        'detailed'
        'diagnostic'

Argumenten hebben ook verwachtingen over het aantal waarden dat kan worden opgegeven. Voorbeelden vindt u in de sectie over argument arity.

Volgorde van opties en argumenten

U kunt opties opgeven voor argumenten of argumenten vóór opties op de opdrachtregel. De volgende opdrachten zijn equivalent:

dotnet add package System.CommandLine --prerelease
dotnet add package --prerelease System.CommandLine

Opties kunnen in elke volgorde worden opgegeven. De volgende opdrachten zijn equivalent:

dotnet add package System.CommandLine --prerelease --no-restore --source https://api.nuget.org/v3/index.json
dotnet add package System.CommandLine --source https://api.nuget.org/v3/index.json --no-restore --prerelease

Als er meerdere argumenten zijn, maakt de volgorde wel uit. De volgende opdrachten zijn niet gelijkwaardig; ze verschillen in de volgorde van de waarden, wat kan leiden tot verschillende resultaten:

myapp argument1 argument2
myapp argument2 argument1

Aliassen

In zowel POSIX als Windows is het gebruikelijk dat sommige opdrachten en opties aliassen hebben. Dit zijn meestal korte formulieren die gemakkelijker te typen zijn. Aliassen kunnen ook worden gebruikt voor andere doeleinden, zoals het simuleren van hoofdlettergevoeligheid en het ondersteunen van alternatieve spelling van een woord.

POSIX-korte formulieren hebben meestal één voorloopafbreekstreepje gevolgd door één teken. De volgende opdrachten zijn equivalent:

dotnet build --verbosity quiet
dotnet build -v quiet

De GNU-standaard raadt automatische aliassen aan. Dat wil zeggen, u kunt elk deel van een lange vorm van een opdracht of optienaam invoeren en die wordt geaccepteerd. Dit gedrag maakt het equivalent van de volgende opdrachtregels:

dotnet publish --output ./publish
dotnet publish --outpu ./publish
dotnet publish --outp ./publish
dotnet publish --out ./publish
dotnet publish --ou ./publish
dotnet publish --o ./publish

System.CommandLine biedt geen ondersteuning voor automatische aliassen. Elke alias moet expliciet worden opgegeven. Zowel opdrachten als opties maken een Aliases eigenschap beschikbaar. Option heeft een constructor die aliassen accepteert als parameters, zodat u een optie met meerdere aliassen op één regel kunt definiëren:

Option<bool> helpOption = new("--help", ["-h", "/h", "-?", "/?"]);
Command command = new("serialize") { helpOption };
command.Aliases.Add("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.

Hoofdlettergevoelig

Namen en aliassen van opdrachten en opties zijn standaard hoofdlettergevoelig volgens de POSIX-conventie en System.CommandLine volgt deze conventie. Als u wilt dat uw CLI niet hoofdlettergevoelig is, definieert u aliassen voor de verschillende schrijfwijzen. Bijvoorbeeld, --additional-probing-path kan de aliassen --Additional-Probing-Path en --ADDITIONAL-PROBING-PATH hebben.

In sommige opdrachtregelhulpprogramma's geeft een verschil in het gebruik van hoofdletters en kleine letters een verschil in functionaliteit aan. Gedraagt zich bijvoorbeeld git clean -X anders dan git clean -x. De .NET CLI is volledig in kleine letters.

Hoofdlettergevoeligheid is niet van toepassing op argumentwaarden voor opties die zijn gebaseerd op opsommingen. Opsommingsnamen komen overeen, ongeacht hoofdletters.

Het -- token

POSIX-conventie interpreteert het token met dubbele streepjes (--)als een escape-mechanisme. Alles dat het token met dubbele streepjes volgt, wordt geïnterpreteerd als argumenten voor de opdracht. Deze functionaliteit kan worden gebruikt om argumenten in te dienen die eruitzien als opties, omdat hiermee wordt voorkomen dat ze worden geïnterpreteerd als opties.

Stel dat myapp een message argument gebruikt, en dat u wilt dat de waarde van message--interactive is. De volgende opdrachtregel kan onverwachte resultaten opleveren.

myapp --interactive

Als myapp geen --interactive-optie heeft, wordt de --interactive-token geïnterpreteerd als een argument. Maar als de app wel een --interactive optie heeft, wordt deze invoer geïnterpreteerd als verwijst naar die optie.

In de volgende opdrachtregel wordt het dubbele streepje-token gebruikt om de waarde van het message argument in te stellen op '--interactive':

myapp -- --interactive
      ^^

System.CommandLine ondersteunt deze functionaliteit met dubbele streepjes.

Scheidingstekens voor optiesargumenten

System.CommandLine hiermee kunt u een spatie, '=' of ':' gebruiken als scheidingsteken tussen een optienaam en het bijbehorende argument. De volgende opdrachten zijn bijvoorbeeld gelijkwaardig:

dotnet build -v quiet
dotnet build -v=quiet
dotnet build -v:quiet

Met een POSIX-conventie kunt u het scheidingsteken weglaten wanneer u een optiealias met één teken opgeeft. De volgende opdrachten zijn bijvoorbeeld gelijkwaardig:

myapp -vquiet
myapp -v quiet

System.CommandLine ondersteunt deze syntaxis standaard.

Argument ariteit

Het argument van een optie of opdracht is het aantal waarden dat kan worden doorgegeven als deze optie of opdracht is opgegeven.

Arity wordt uitgedrukt met een minimumwaarde en een maximumwaarde, zoals in de volgende tabel wordt geïllustreerd:

Minuut Max Voorbeeld van geldigheid Voorbeeld
0 0 Geldig: --bestand
Ongeldig: --file a.json
Ongeldig: --file a.json --file b.json
0 1 Geldig: --vlag
Geldig: --vlag waar
Geldig: --vlag onwaar
Ongeldig: --vlag onwaar --vlag onwaar
1 1 Geldig: --file a.json
Ongeldig: --bestand
Ongeldig: --file a.json --file b.json
0 n Geldig: --bestand
Geldig: --file a.json
Geldig: --file a.json --file b.json
1 n Geldig: --file a.json
Geldig: --file a.json b.json
Ongeldig: --bestand

System.CommandLine heeft een ArgumentArity struct voor het definiëren van arity, met de volgende waarden:

  • Zero - Er zijn geen waarden toegestaan.
  • ZeroOrOne - Kan één waarde of geen waarde hebben.
  • ExactlyOne - Moet één waarde hebben.
  • ZeroOrMore - Kan één waarde, meerdere waarden of geen waarden hebben.
  • OneOrMore - Kan meerdere waarden hebben; moet ten minste één waarde hebben.

U kunt arity expliciet 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 ariteit
Boolean ArgumentArity.ZeroOrOne
Verzamelingstypen ArgumentArity.ZeroOrMore
Al het andere ArgumentArity.ExactlyOne

Optie-overschrijvingen

Als het maximum voor arity 1 is, System.CommandLine kan nog steeds worden geconfigureerd om meerdere exemplaren van een optie te accepteren. In dat geval overschrijft het laatste exemplaar van een herhaalde optie alle eerdere exemplaren. In het volgende voorbeeld wordt de waarde 2 doorgegeven aan de myapp opdracht.

myapp --delay 3 --message example --delay 2

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 AllowMultipleArgumentsPerToken op true. Met deze instelling kunt u de volgende opdrachtregel invoeren.

myapp --items one two three

Dezelfde instelling heeft een ander effect als de maximale argument ariteit 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

Optiebundeling

POSIX raadt u aan om bundeling van opties met één teken, ook wel stacking genoemd, te ondersteunen. Gebundelde opties zijn één karakter lange aliassen die samen zijn opgegeven achter één enkel koppelteken. Alleen de laatste optie kan een argument opgeven. De volgende opdrachtregels zijn bijvoorbeeld gelijkwaardig:

git clean -f -d -x
git clean -fdx

Als er een argument wordt opgegeven na een optiebundel, is dit van toepassing op de laatste optie in de bundel. De volgende opdrachtregels zijn equivalent:

myapp -a -b -c arg
myapp -abc arg

In beide varianten in dit voorbeeld is het argument arg alleen van toepassing op de optie -c.

Booleaanse opties (vlaggen)

Als true of false wordt doorgegeven voor een optie met een bool argument, wordt deze geparseerd zoals verwacht. Maar een optie waarvan het argumenttype bool is, vereist meestal geen argument. Booleaanse opties, ook wel 'vlaggen' genoemd, hebben meestal een arity van ZeroOrOne. De aanwezigheid van de optienaam op de opdrachtregel, zonder argument erop te volgen, resulteert in een standaardwaarde van true. Het ontbreken van de optienaam in de opdrachtregelinvoer resulteert in een waarde van false. Als de myapp opdracht de waarde van een Booleaanse optie met de naam --interactiveafdrukt, wordt met de volgende invoer de volgende uitvoer gemaakt:

myapp
myapp --interactive
myapp --interactive false
myapp --interactive true

False
True
False
True

Versieoptie

Apps die zijn gebouwd op System.CommandLine geven automatisch het versienummer op als reactie op de --version-optie die wordt gebruikt met de hoofdopdracht. Voorbeeld:

dotnet --version

6.0.100

Antwoordbestanden

Een antwoordbestand is een bestand dat een set tokens voor een opdrachtregel-app bevat. Antwoordbestanden zijn een functie van System.CommandLine die nuttig is in twee scenario's.

  • Als u een opdrachtregel-app wilt aanroepen door invoer op te geven die langer is dan de tekenlimiet van de terminal.
  • Als u dezelfde opdracht herhaaldelijk wilt aanroepen zonder de hele regel opnieuw te typen.

Als u een antwoordbestand wilt gebruiken, voert u de bestandsnaam in die wordt voorafgegaan door een @ teken, waar u op de regel opdrachten, opties en argumenten wilt invoegen. De bestandsextensie .rsp is een gangbare conventie, maar u kunt elke bestandsextensie gebruiken.

De volgende regels zijn gelijkwaardig:

dotnet build --no-restore --output ./build-output/
dotnet @sample1.rsp
dotnet build @sample2.rsp --output ./build-output/

Inhoud van sample1.rsp:

build
--no-restore
--output
./build-output/

Inhoud van sample2.rsp:

--no-restore

Hier volgen syntaxisregels die bepalen hoe de tekst in een antwoordbestand wordt geïnterpreteerd:

  • Tokens worden gescheiden door spaties. Een lijn die Goedemorgen bevat! wordt behandeld als twee tokens, Goed en morgen!.
  • Meerdere tokens tussen aanhalingstekens worden geïnterpreteerd als één token. Een regel met 'Goedemorgen!' wordt behandeld als één token, Goedemorgen!.
  • Tekst tussen een # symbool en het einde van de regel wordt behandeld als een opmerking en genegeerd.
  • Tokens die zijn voorafgegaan door @ , kunnen verwijzen naar aanvullende antwoordbestanden.
  • Het antwoordbestand kan meerdere regels tekst bevatten. De lijnen worden samengevoegd en geïnterpreteerd als een reeks tokens.

Richtlijnen

System.CommandLine introduceert een syntactisch element dat een richtlijn wordt genoemd die wordt vertegenwoordigd door het Directive type. De [diagram] richtlijn is bijvoorbeeld een ingebouwde richtlijn. Wanneer u [diagram] opneemt na de naam van de app, toont System.CommandLine een diagram van het parseringsresultaat in plaats van de opdrachtregelapplicatie aan te roepen.

dotnet [diagram] build --no-restore --output ./build-output/
       ^-----^

[ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ]

Het doel van richtlijnen is om overkoepelende functionaliteit te bieden die kan worden toegepast op commandoregelapplicaties. Omdat instructies syntactisch verschillen van de eigen syntaxis van de app, kunnen ze functionaliteit bieden die van toepassing is op alle apps.

Een richtlijn moet voldoen aan de volgende syntaxisregels:

  • Het is een token op de opdrachtregel die na de naam van de app komt, maar vóór eventuele subopdrachten of opties.
  • Het is omsloten door vierkante haken.
  • Het bevat geen spaties.

Een niet-herkende instructie wordt genegeerd zonder een parseringsfout te veroorzaken.

Een richtlijn kan een argument bevatten, gescheiden van de naam van de richtlijn door een dubbele punt.

De volgende instructies zijn ingebouwd:

De richtlijn [diagram]

Zowel gebruikers als ontwikkelaars kunnen het nuttig vinden om te zien hoe een app een bepaalde invoer interpreteert. Een van de standaardfuncties van een System.CommandLine app is de [diagram] instructie, waarmee u een voorbeeld kunt bekijken van het resultaat van het parseren van opdrachtinvoer. Voorbeeld:

myapp [diagram] --delay not-an-int --interactive --file filename.txt extra

![ myapp [ --delay !<not-an-int> ] [ --interactive <True> ] [ --file <filename.txt> ] *[ --fgcolor <White> ] ]   ???--> extra

In het voorgaande voorbeeld:

  • De opdracht (myapp), de onderliggende opties en de argumenten voor deze opties worden gegroepeerd met vierkante haken.
  • Voor de optie-uitkomst [ --delay !<not-an-int> ] geeft ! een parseringsfout aan. De waarde not-an-int voor een int optie kan niet worden geparseerd naar het verwachte type. De fout wordt ook gemarkeerd bij ! de opdracht die de foutieve optie bevat: ![ myapp....
  • Voor het resultaat van de optie *[ --fgcolor <White> ]is de optie niet opgegeven op de opdrachtregel, dus de geconfigureerde standaardwaarde is gebruikt. White is de effectieve waarde voor deze optie. Het sterretje geeft aan dat de waarde de standaardwaarde is.
  • ???--> verwijst naar invoer die niet overeenkomt met de opdrachten of opties van de app.

Richtlijn voorstellen

Met de [suggest] instructie kunt u zoeken naar opdrachten wanneer u de exacte opdracht niet weet.

dotnet [suggest] buil

build
build-server
msbuild

Zie ook

  • Last updated on