Riktlinjer för design

Följande avsnitt innehåller vägledning för att utforma ett CLI. Tänk på vad din app förväntar sig på kommandoraden som liknar vad en REST API-server förväntar sig i URL:en. Konsekventa regler för REST-API:er är det som gör dem lätt användbara för klientappsutvecklare. På samma sätt får användare av dina kommandoradsappar en bättre upplevelse om CLI-designen följer vanliga mönster.

När du har skapat en CLI är det svårt att ändra den, särskilt om användarna har använt din CLI i skript som de förväntar sig att fortsätta köra.

Symboler

Kommandon och underkommandon

Om ett kommando har underkommandon ska kommandot fungera som ett område eller en grupperingsidentifierare för underkommandona i stället för att ange en åtgärd. När du anropar appen anger du grupperingskommandot och en av dess underkommandon. Försök till exempel att köra dotnet tool, och du får ett felmeddelande eftersom kommandot tool endast identifierar en grupp verktygsrelaterade underkommandon, såsom install och list. Du kan köra dotnet tool install, men dotnet tool i sig skulle vara ofullständig.

Ett av sätten som definierade områden hjälper dina användare är att det organiserar hjälpinformationen.

Inom ett CLI finns det ofta ett implicit område. I .NET CLI är till exempel det implicita området projektet, och i Docker CLI är det avbildningen. Som ett resultat kan du använda dotnet build utan att inkludera ett område. Överväg om din CLI har ett implicit område. Om det gör det bör du överväga om användaren ska kunna inkludera eller utelämna det, som i docker build och docker image build. Om du valfritt tillåter att det implicita området skrivs in av din användare, får du också automatiskt hjälp och tab-komplettering för den här gruppen av kommandon. Tillhandahåll den valfria användningen av den implicita gruppen genom att definiera två kommandon som utför samma operation.

Alternativ som parametrar

Alternativen ska tillhandahålla parametrar till kommandon, snarare än att specificera handlingar själva. Detta är en rekommenderad designprincip, även om den inte alltid följs av System.CommandLine (--help visar hjälpinformation).

Namngivning

Kortformsalias

Generellt sett rekommenderar vi att du minimerar antalet korta alias för alternativ som du definierar.

I synnerhet bör du undvika att använda någon av följande alias på ett sätt som avviker från deras vanliga användning i .NET CLI och andra .NET-kommandoradsapplikationer.

• -i för --interactive.

  Det här alternativet signalerar till användaren att de kan uppmanas att ange indata till frågor som kommandot behöver besvaras. Till exempel, att be om ett användarnamn. Cli kan användas i skript, så var försiktig när du uppmanar användare som inte har angett den här växeln.

• -o för --output.

  Vissa kommandon skapar filer när de körs. Det här alternativet bör användas för att avgöra var filerna ska finnas. I de fall där en enskild fil skapas bör det här alternativet vara en filsökväg. I de fall där många filer skapas bör det här alternativet vara en katalogsökväg.

• -v för --verbosity.

  Kommandon ger ofta utdata till användaren på konsolen; det här alternativet används för att specificera mängden utdata som användaren begär. För mer information, se alternativet --verbosity senare i denna artikel.

Det finns också några alias vars vanliga användning är begränsad till .NET CLI:n. Du kan använda dessa alias för andra alternativ i dina appar, men var medveten om risken för förvirring.

• -c för --configuration

  Det här alternativet refererar ofta till en med namnet Build Configuration, som Debug eller Release. Du kan använda vilket namn du vill för en konfiguration, men de flesta verktyg förväntar sig ett av dem. Den här inställningen används ofta för att konfigurera andra egenskaper på ett sätt som passar för den konfigurationen, till exempel genom att göra mindre kodoptimering när du skapar konfigurationen Debug . Överväg det här alternativet om ditt kommando har olika driftlägen.

• -f för --framework

  Detta alternativ används för att välja en enda Target Framework Moniker (TFM) för att köra, så om din CLI-applikation beter sig olika beroende på vilken TFM som väljs, bör du stödja denna flagga.

• -p för --property

  Om din applikation till slut anropar MSBuild, kommer användaren ofta att behöva anpassa det anropet på något sätt. Detta alternativ möjliggör att MSBuild-egenskaper anges i kommandoraden och vidarebefordras till det underliggande MSBuild-anropet. Om din app inte använder MSBuild men behöver en uppsättning nyckel-värde-par, överväg att använda samma alternativnamn för att dra nytta av användarnas förväntningar.

• -r för --runtime

  Om din applikation kan köras på olika runtime-miljöer, eller har logik som är specifik för en viss runtime, överväg att stödja detta alternativ som ett sätt att ange en Runtime Identifier. Om din app stöder --runtimekan du överväga att stödja --os och --arch även. Dessa alternativ låter dig specificera endast operativsystemet eller arkitekturdelen av RID, medan den del som inte specificeras bestäms utifrån den aktuella plattformen. För mer information, se dotnet publish.

Korta namn

Gör namn för kommandon, alternativ och argument så korta och lätta att stava som möjligt. Om class är tillräckligt tydligt, gör inte kommandot classification.

Namn med gemener

Definiera endast namn i gemener, men du kan göra alias med versaler för att göra kommandon eller alternativ skiftlägesokänsliga.

namn i kebab-fall

Använd kebab case för att skilja på ord. Till exempel --additional-probing-path.

Pluralisering

Inom en app, var konsekvent i pluralisering. Till exempel, blanda inte plural och singular namn för alternativ som kan ha flera värden (maximal aritet större än ett).

Verb vs. substantiv

Använd verb istället för substantiv för kommandon som hänvisar till handlingar (de utan underkommandon), till exempel: dotnet workload remove, inte dotnet workload removal. Och använd substantiv istället för verb för alternativ, till exempel: --configuration, inte --configure.

Alternativet --verbosity

System.CommandLine-applikationer erbjuder vanligtvis ett --verbosity-alternativ som specificerar hur mycket output som skickas till konsolen. Här är de fem standardinställningarna:

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

Dessa är standardnamnen, men befintliga appar använder ibland Silent istället för Quiet, och Trace, Debug eller Verbose istället för Diagnostic.

Varje app definierar sina egna kriterier som avgör vad som visas på varje nivå. Vanligtvis behöver en app bara tre nivåer:

• Tyst
• Normalt
• Diagnostik

Om en app inte behöver fem olika nivåer, bör alternativet ändå definiera samma fem inställningar. I så fall kommer Minimal och Normal att ge samma resultat, och Detailed och Diagnostic kommer också att vara desamma. På så sätt kan användarna bara skriva det de är bekanta med, så används den bästa passformen.

Förväntningen för Quiet är att inget output visas på konsolen. Men om en app erbjuder ett interaktivt läge bör appen göra något av följande:

• Visa uppmaningar för inmatning när --interactive anges, även om --verbosity är Quiet.
• Tillåt inte användningen av --verbosity Quiet och --interactive tillsammans.

Annars väntar appen på indata utan att tala om för användaren vad den väntar på. Det verkar som om programmet frös och användaren har ingen aning om att programmet väntar på indata.

Om du definierar alias, använd -v för --verbosity och gör -v utan ett argument till ett alias för --verbosity Diagnostic. Använd -q för --verbosity Quiet.

.NET CLI- och POSIX-konventionerna

.NET CLI följer inte konsekvent alla POSIX-konventioner.

Dubbelstreck

Flera kommandon i .NET CLI har en speciell implementering av tvåstreckstoken. I fallet med dotnet run, dotnet watch och dotnet tool run skickas tokens som följer -- till appen som körs av kommandot. Till exempel:

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

I det här exemplet skickas --project-alternativet till dotnet run-kommandot, och --message-alternativet med sitt argument skickas som ett kommandoradsalternativ till myapp när det körs.

---tokenet är inte alltid nödvändigt när du skickar alternativ till en app som du kör med hjälp av dotnet run. Utan dubbelstreck överför kommandot dotnet run automatiskt alla alternativ som inte känns igen som tillämpliga på dotnet run självt eller på MSBuild till den körande appen. Så följande kommandorader är likvärdiga eftersom dotnet run inte känner igen argumenten och alternativen.

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

Utelämnande av skiljetecknet mellan alternativ och argument

.NET CLI stöder inte POSIX-konventionen som låter dig utelämna avgränsaren när du specificerar en alias för en enskild teckenoption.

Flera argument utan att upprepa alternativets namn

.NET CLI accepterar inte flera argument för ett alternativ utan att upprepa alternativnamnet.

Booleska alternativ

I .NET CLI resulterar vissa Booleska alternativ i samma beteende när du skickar false som när du skickar true. Detta beteende uppstår när .NET CLI-kod som implementerar alternativet endast kontrollerar för närvaro eller frånvaro av alternativet och ignorerar dess värde. Ett exempel är --no-restore för dotnet build kommandot. Använd --no-restore false så kommer återställningsåtgärden att hoppas över på samma sätt som när du anger --no-restore true eller --no-restore.

Kebabväska

I vissa fall använder .NET CLI inte kebab-case för kommando-, alternativ- eller argumentnamn. Till exempel finns det ett .NET CLI-alternativ som heter --additionalprobingpath istället för --additional-probing-path.

Se även

• Vägledning för CLI-design med öppen källkod
• GNU-standarder