Ontwerprichtlijnen

De volgende secties bevatten richtlijnen voor het ontwerpen van een CLI. Denk aan wat je app verwacht op de opdrachtregel, net zoals wat een REST API-server van een 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 deze te wijzigen, met name als uw gebruikers uw CLI hebben gebruikt in scripts die ze verwachten te blijven uitvoeren.

Symbolen

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 het definiëren van gebieden uw gebruikers helpt, is zodat de Help-uitvoer wordt georganiseerd.

Binnen een CLI is er vaak een impliciet gebied. Bijvoorbeeld, in de .NET CLI is het impliciete gebied het project, en in de Docker CLI is het de afbeelding. Als gevolg hiervan kunt u dotnet build gebruiken zonder een gebied op te nemen. Overweeg of uw CLI een impliciet gebied heeft. Als dit 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 het niet altijd door System.CommandLine wordt gevolgd (--help geeft helpinformatie weer).

Naamgeving

Korte pseudoniemen

Over het algemeen is het raadzaam om het aantal korte aliasopties 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 deze mogelijk wordt gevraagd om invoer voor vragen die de opdracht moet beantwoorden. Bijvoorbeeld het vragen om een gebruikersnaam. Uw CLI kan worden gebruikt in scripts, dus wees voorzichtig bij het waarschuwen van gebruikers die deze optie 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 aangemaakt, moet deze optie een mapadres 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 --runtime, kunt u ondersteuning --os en --arch ook overwegen. 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 zo eenvoudig mogelijk om te spellen. Als het bijvoorbeeld class duidelijk genoeg is, moet u de opdracht classificationniet maken.

Namen in kleine letters

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

Namen in kebabnotatie

Gebruik kebab case 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):

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:

• Rustig
• Normaal
• Diagnostiek

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

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

• Toon prompts voor invoer wanneer --interactive is gespecificeerd, zelfs als --verbosityQuiet is.
• 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 u -v voor --verbosity en maakt u van -v 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 run, dotnet watch en dotnet tool run worden tokens die volgen op -- 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 van 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 leiden sommige Booleaanse opties tot hetzelfde gedrag wanneer u zowel false als true doorgeeft. 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. Geef --no-restore false door en de herstelbewerking wordt overgeslagen op dezelfde manier als wanneer u --no-restore true of --no-restore opgeeft.

kebab-notatie

In sommige gevallen gebruikt de .NET CLI geen kebab 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

• Opensource CLI-ontwerprichtlijnen
• GNU-standaarden