Delen via

Overzicht van opdrachtregelsyntaxis voor 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 worden de opdrachtregelsyntaxis uitgelegd die System.CommandLine wordt herkend. De informatie is nuttig voor gebruikers en ontwikkelaars van .NET-opdrachtregel-apps, waaronder de .NET CLI.

Tokens

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, , dotnet-suggestinstall, , --global, --verbosityen quiet.

Tokens worden geïnterpreteerd als opdrachten, opties of argumenten. De opdrachtregel-app die 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:

Token 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"

Opdracht

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.
  • install Is dotnet tool installeen opdracht die een actie aangeeft en tool een opdracht is waarmee een groep gerelateerde opdrachten wordt opgegeven. Er zijn andere hulpprogramma-gerelateerde opdrachten, zoals tool uninstall, tool listen tool update.

Hoofdopdrachten

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.

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.

Opties

Een optie is een benoemde parameter die kan worden doorgegeven aan een opdracht. POSIX-CLIs geven meestal het voorvoegsel van de optienaam met twee afbreekstreepjes (--). In het volgende voorbeeld ziet u twee opties:

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

Zoals in dit voorbeeld wordt geïllustreerd, is de waarde van de optie mogelijk expliciet (quietvoor--verbosity) of impliciet (er volgt niets).--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.

Argumenten

Een argument is een waarde die wordt doorgegeven aan een optie of een opdracht. In de volgende voorbeelden ziet u een argument voor de verbosity optie en een argument voor de build opdracht.

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

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

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

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

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

Sommige opties hebben vereiste argumenten. Voor de .NET CLI --output is bijvoorbeeld een mapnaamargument vereist. Als het argument niet is opgegeven, mislukt de opdracht.

Argumenten kunnen verwachte typen hebben en System.CommandLine een foutbericht weergeven als een argument niet kan worden geparseerd in het verwachte type. De volgende opdrachtfouten zijn bijvoorbeeld omdat 'stil' niet een van de geldige waarden is voor --verbosity:

dotnet build --verbosity silent

Cannot parse argument 'silent' for option '-v' as expected type 'Microsoft.DotNet.Cli.VerbosityOptions'. Did you mean one of the following?
Detailed
Diagnostic
Minimal
Normal
Quiet

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 noodzakelijkerwijs equivalent:

myapp argument1 argument2
myapp argument2 argument1

Met deze opdrachten wordt een lijst met dezelfde waarden doorgegeven aan de code van de opdrachthandler, maar ze verschillen in de volgorde van de waarden, wat kan leiden tot verschillende resultaten.

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 gezegd, u kunt een deel van een opdracht of optienaam voor een lang formulier invoeren en deze 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.

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 hoofdlettergebruiksalternatieven. Kan bijvoorbeeld --additional-probing-path aliassen --Additional-Probing-Path en --ADDITIONAL-PROBING-PATH.

In sommige opdrachtregelprogramma's geeft een verschil in hoofdletters een verschil in functie aan. Gedraagt zich bijvoorbeeld git clean -X anders dan git clean -x. De .NET CLI is allemaal 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 de waarde wilt hebben--interactive.message De volgende opdrachtregel kan onverwachte resultaten opleveren.

myapp --interactive

Als myapp er geen optie is --interactive , wordt het --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 arity

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:

Min. Max. Voorbeeld van geldigheid Opmerking
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 hebben, kan geen waarden 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.

Arity kan vaak worden afgeleid van het type. Een optie heeft bijvoorbeeld int een arity van ExactlyOneen een List<int> optie heeft arity OneOrMore.

Onderdrukkingen van opties

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

Als het maximum voor arity meer dan één is, System.CommandLine kan worden geconfigureerd om meerdere argumenten voor één optie te accepteren zonder de naam van de optie te herhalen.

In het volgende voorbeeld bevat de lijst die is doorgegeven aan de myapp opdracht 'a', 'b', 'c' en 'd':

myapp --list a b c --list d

Optiebundeling

POSIX raadt u aan om bundeling van opties met één teken, ook wel stacking genoemd, te ondersteunen. Gebundelde opties zijn aliassen met één teken die samen zijn opgegeven na één koppeltekenvoorvoegsel. 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 voor een optie waarvan het argumenttype bool doorgaans geen argument is vereist, moet er geen argument worden opgegeven. 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

De optie --help

Opdrachtregel-apps bieden doorgaans een optie om een korte beschrijving weer te geven van de beschikbare opdrachten, opties en argumenten. System.CommandLine genereert automatisch Help-uitvoer. Voorbeeld:

dotnet list --help

Description:
  List references or packages of a .NET project.

Usage:
  dotnet [options] list [<PROJECT | SOLUTION>] [command]

Arguments:
  <PROJECT | SOLUTION>  The project or solution file to operate on. If a file is not specified, the command will search the current directory for one.

Options:
  -?, -h, --help  Show command line help.

Commands:
  package    List all package references of the project or solution.
  reference  List all project-to-project references of the project.

App-gebruikers zijn mogelijk gewend aan verschillende manieren om hulp op verschillende platforms aan te vragen, zodat apps die zijn gebouwd op System.CommandLine veel manieren om hulp te vragen, reageren. De volgende opdrachten zijn allemaal equivalent:

dotnet --help
dotnet -h
dotnet /h
dotnet -?
dotnet /?

In de Help-uitvoer worden niet noodzakelijkerwijs alle beschikbare opdrachten, argumenten en opties weergegeven. Sommige hiervan zijn mogelijk verborgen, wat betekent dat ze niet worden weergegeven in de Help-uitvoer, maar ze kunnen worden opgegeven op de opdrachtregel.

De optie --version

Apps die zijn gebouwd 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 die System.CommandLine 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 lijn 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 regels worden samengevoegd en geïnterpreteerd als een reeks tokens.

Richtlijnen

System.CommandLine introduceert een syntactisch element dat een richtlijn wordt genoemd. De [parse] richtlijn is een voorbeeld. Wanneer u de naam van de app opneemt [parse] , System.CommandLine wordt een diagram van het parseringsresultaat weergegeven in plaats van de opdrachtregel-app aan te roepen:

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

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

Het doel van instructies is om kruislingse functionaliteit te bieden die kan worden toegepast op opdrachtregel-apps. 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 zit tussen 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 [parse] richtlijn

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 [parse] instructie, waarmee u een voorbeeld kunt bekijken van het resultaat van het parseren van opdrachtinvoer. Voorbeeld:

myapp [parse] --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 het resultaat van de optie [ --delay !<not-an-int> ]! wordt een parseringsfout aangegeven. De waarde not-an-int voor een int optie kan niet worden geparseerd naar het verwachte type. De fout wordt ook gemarkeerd voor ! de opdracht die de fout 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.

De [suggest] richtlijn

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

dotnet [suggest] buil

build
build-server
msbuild

Ontwerprichtlijnen

De volgende secties bevatten richtlijnen die u wordt aangeraden te volgen bij het ontwerpen van een CLI. Bedenk wat uw app verwacht op de opdrachtregel, net zoals een REST API-server in de URL verwacht. Consistente regels voor REST API's maken ze gemakkelijk bruikbaar voor client-app-ontwikkelaars. Op dezelfde manier hebben gebruikers van uw opdrachtregel-apps een betere ervaring als het CLI-ontwerp algemene patronen volgt.

Zodra u een CLI hebt gemaakt, is het moeilijk om te wijzigen, met name als uw gebruikers uw CLI hebben gebruikt in scripts die ze verwachten te blijven uitvoeren. De richtlijnen hier zijn ontwikkeld na de .NET CLI en volgen deze richtlijnen niet altijd. We werken de .NET CLI bij, waar we dit kunnen doen zonder wijzigingen die fouten veroorzaken. Een voorbeeld van dit werk is het nieuwe ontwerp voor dotnet new .NET 7.

Opdrachten en subopdrachten

Als een opdracht subopdrachten heeft, moet de opdracht fungeren als een gebied of een groeperings-id voor de subopdrachten in plaats van een actie op te geven. Wanneer u de app aanroept, geeft u de groepsopdracht en een van de bijbehorende subopdrachten op. Probeer bijvoorbeeld uit te voeren dotnet toolen u krijgt een foutbericht omdat de tool opdracht alleen een groep hulpprogramma-gerelateerde subopdrachten identificeert, zoals install en list. U kunt uitvoeren dotnet tool install, maar dotnet tool op zichzelf zou onvolledig zijn.

Een van de manieren waarop u gebieden definieert, is dat de Help-uitvoer wordt ingedeeld.

Binnen een CLI is er vaak een impliciet gebied. In de .NET CLI is het impliciete gebied bijvoorbeeld het project en in de Docker CLI is dit de installatiekopieën. Als gevolg hiervan kunt u zonder dotnet build een gebied gebruiken. Overweeg of uw CLI een impliciet gebied heeft. Als dat het geval is, kunt u overwegen of de gebruiker deze optioneel mag opnemen of weglaten zoals in docker build en docker image build. Als u optioneel het impliciete gebied toestaat dat door uw gebruiker wordt getypt, hebt u ook automatisch hulp en tabvoltooiing voor deze groepering van opdrachten. Geef het optionele gebruik van de impliciete groep op door twee opdrachten te definiëren die dezelfde bewerking uitvoeren.

Opties als parameters

Opties moeten parameters voor opdrachten bieden in plaats van zelf acties op te geven. Dit is een aanbevolen ontwerpprincipe, hoewel dit niet altijd wordt gevolgd System.CommandLine door (--help geeft help-informatie weer).

Korte aliassen

Over het algemeen raden we u aan om het aantal korte-formulieroptiealiassen dat u definieert, te minimaliseren.

Vermijd met name het gebruik van een van de volgende aliassen anders dan het gebruikelijke gebruik in de .NET CLI en andere .NET-opdrachtregel-apps:

  • -i voor --interactive.

    Met deze optie wordt aan de gebruiker aangegeven dat er mogelijk om invoer wordt gevraagd voor vragen die door de opdracht moeten worden beantwoord. Bijvoorbeeld het vragen om een gebruikersnaam. Uw CLI kan worden gebruikt in scripts, dus wees voorzichtig bij het vragen van gebruikers die deze switch niet hebben opgegeven.

  • -o voor --output.

    Sommige opdrachten produceren bestanden als gevolg van hun uitvoering. Deze optie moet worden gebruikt om te bepalen waar die bestanden zich moeten bevinden. In gevallen waarin één bestand wordt gemaakt, moet deze optie een bestandspad zijn. In gevallen waarin veel bestanden worden gemaakt, moet deze optie een mappad zijn.

  • -v voor --verbosity.

    Opdrachten bieden vaak uitvoer aan de gebruiker op de console; deze optie wordt gebruikt om de hoeveelheid uitvoer op te geven die de gebruikersaanvragen aanvragen. Zie de --verbosity optie verderop in dit artikel voor meer informatie.

Er zijn ook enkele aliassen met algemeen gebruik beperkt tot de .NET CLI. U kunt deze aliassen gebruiken voor andere opties in uw apps, maar houd rekening met de mogelijkheid van verwarring.

  • -c voor --configuration

    Deze optie verwijst vaak naar een benoemde buildconfiguratie, zoals Debug of Release. U kunt elke gewenste naam voor een configuratie gebruiken, maar de meeste hulpprogramma's verwachten een van deze. Deze instelling wordt vaak gebruikt om andere eigenschappen te configureren op een manier die zinvol is voor die configuratie, bijvoorbeeld om minder codeoptimalisatie uit te voeren bij het bouwen van de Debug configuratie. Houd rekening met deze optie als uw opdracht verschillende bewerkingsmodi heeft.

  • -f voor --framework

    Deze optie wordt gebruikt om één Target Framework Moniker (TFM) te selecteren voor uitvoering, dus als uw CLI-toepassing verschillend gedrag heeft op basis van welke TFM is gekozen, moet u deze vlag ondersteunen.

  • -p voor --property

    Als uw toepassing uiteindelijk MSBuild aanroept, moet de gebruiker die aanroep vaak op een of andere manier aanpassen. Met deze optie kunnen MSBuild-eigenschappen worden opgegeven op de opdrachtregel en worden doorgegeven aan de onderliggende MSBuild-aanroep. Als uw app geen GEBRUIK maakt van MSBuild, maar een set sleutel-waardeparen nodig heeft, kunt u overwegen om dezelfde optienaam te gebruiken om te profiteren van de verwachtingen van gebruikers.

  • -r voor --runtime

    Als uw toepassing kan worden uitgevoerd op verschillende runtimes of runtimespecifieke logica heeft, kunt u overwegen deze optie te ondersteunen als een manier om een runtime-id op te geven. Als uw app ondersteuning biedt voor --runtime, kunt u overwegen ondersteuning te bieden --os en --arch ook. Met deze opties kunt u alleen het besturingssysteem of de architectuuronderdelen van de RID opgeven, zodat het onderdeel niet wordt bepaald op basis van het huidige platform. Zie dotnet publish voor meer informatie.

Korte namen

Maak namen voor opdrachten, opties en argumenten zo kort en eenvoudig mogelijk te spellen. Als het bijvoorbeeld class duidelijk genoeg is, maakt u de opdracht classificationniet.

Namen van kleine letters

Definieer alleen namen in kleine letters, behalve dat u hoofdletteraliassen kunt maken om opdrachten of opties hoofdlettergevoelig te maken.

Namen van namen van hoofdletters

Gebruik de hoofdletters om woorden te onderscheiden. Bijvoorbeeld: --additional-probing-path.

Pluralisatie

Binnen een app moet u consistent zijn in pluralisatie. Combineer bijvoorbeeld geen meervouds- en enkelvoudige namen voor opties die meerdere waarden kunnen hebben (maximale ariteit groter dan één):

Optienamen Consistentie
--additional-probing-paths en --sources ✔️
--additional-probing-path en --source ✔️
--additional-probing-paths en --source ❌
--additional-probing-path en --sources ❌

Werkwoorden versus zelfstandige naamwoorden

Gebruik werkwoorden in plaats van zelfstandige naamwoorden voor opdrachten die verwijzen naar acties (zonder subopdrachten eronder), bijvoorbeeld: dotnet workload remove, niet dotnet workload removal. En gebruik zelfstandige naamwoorden in plaats van werkwoorden voor opties, bijvoorbeeld: --configuration, niet --configure.

De --verbosity optie

System.CommandLine toepassingen bieden doorgaans een --verbosity optie die aangeeft hoeveel uitvoer naar de console wordt verzonden. Dit zijn de standaard vijf instellingen:

  • Q[uiet]
  • M[inimal]
  • N[ormal]
  • D[etailed]
  • Diag[nostic]

Dit zijn de standaardnamen, maar bestaande apps gebruiken Silent soms in plaats van Quiet, en Trace, Debugof Verbose in plaats van Diagnostic.

Elke app definieert zijn eigen criteria die bepalen wat er op elk niveau wordt weergegeven. Normaal gesproken heeft een app slechts drie niveaus nodig:

  • Quiet
  • Normaal
  • Diagnose

Als een app geen vijf verschillende niveaus nodig heeft, moet de optie nog steeds dezelfde vijf instellingen definiëren. In dat geval Minimal zal deze Normal dezelfde uitvoer produceren en DetailedDiagnostic hetzelfde zijn. Hierdoor kunnen uw gebruikers gewoon typen waar ze bekend mee zijn en de beste pasvorm wordt gebruikt.

De verwachting Quiet is dat er geen uitvoer wordt weergegeven op de console. Als een app echter een interactieve modus biedt, moet de app een van de volgende alternatieven uitvoeren:

  • Geeft prompts weer voor invoer wanneer --interactive is opgegeven, zelfs als --verbosity dat het is Quiet.
  • Het gebruik van --verbosity Quiet en --interactive samen niet toe te laten.

Anders wacht de app op invoer zonder de gebruiker te vertellen waar deze op wacht. Het lijkt erop dat uw toepassing bevroren is en dat de gebruiker geen idee heeft dat de toepassing wacht op invoer.

Als u aliassen definieert, gebruikt -v u hiervoor --verbosity en maakt -v u zonder een argument een alias voor --verbosity Diagnostic. Gebruiken -q voor --verbosity Quiet.

De .NET CLI- en POSIX-conventies

De .NET CLI volgt niet consistent alle POSIX-conventies.

Dubbel streepje

Verschillende opdrachten in de .NET CLI hebben een speciale implementatie van het token met dubbele streepjes. In het geval van dotnet runtokens dotnet watchdie volgen--, dotnet tool runworden tokens doorgegeven aan de app die door de opdracht wordt uitgevoerd. Voorbeeld:

dotnet run --project ./myapp.csproj -- --message "Hello world!"
                                    ^^

In dit voorbeeld wordt de --project optie doorgegeven aan de dotnet run opdracht en wordt de --message optie met het argument ervan doorgegeven als een opdrachtregeloptie aan myapp wanneer deze wordt uitgevoerd.

Het -- token is niet altijd vereist voor het doorgeven van opties aan een app die u uitvoert met behulp van dotnet run. Zonder het dubbele streepje wordt de dotnet run opdracht automatisch doorgegeven aan de app waarbij opties worden uitgevoerd die niet worden herkend als van toepassing op dotnet run zichzelf of op MSBuild. De volgende opdrachtregels zijn dus gelijkwaardig omdat dotnet run de argumenten en opties niet worden herkend:

dotnet run -- quotes read --delay 0 --fg-color red
dotnet run quotes read --delay 0 --fg-color red

Weglating van het scheidingsteken voor optie-naar-argument

De .NET CLI biedt geen ondersteuning voor de POSIX-conventie waarmee u het scheidingsteken weglaat wanneer u een alias voor één teken opgeeft.

Meerdere argumenten zonder de naam van de optie te herhalen

De .NET CLI accepteert niet meerdere argumenten voor één optie zonder de naam van de optie te herhalen.

Booleaanse opties

In de .NET CLI resulteren sommige Booleaanse opties in hetzelfde gedrag wanneer u doorgeeft als wanneer u doorgeeft falsetrue. Dit gedrag treedt op wanneer .NET CLI-code waarmee de optie wordt geïmplementeerd, alleen wordt gecontroleerd op de aanwezigheid of afwezigheid van de optie, waarbij de waarde wordt genegeerd. Een voorbeeld is --no-restore voor de dotnet build opdracht. Doorgeven no-restore false en de herstelbewerking wordt overgeslagen hetzelfde als wanneer u opgeeft no-restore true of no-restore.

De case Van Den

In sommige gevallen wordt in de .NET CLI geen gebruikgemaakt van de case voor opdrachten, opties of argumentnamen. Er is bijvoorbeeld een .NET CLI-optie met de naam --additionalprobingpath in plaats van --additional-probing-path.

Zie ook