設計ガイダンス

次のセクションでは、CLI を設計する際に従うことをお勧めするガイダンスを提示します。 アプリがコマンド ラインで期待しているものは、REST API サーバーが URL で想定しているものと同じように考えてください。 REST API の一貫した規則によって、クライアント アプリ開発者が簡単に使用できるようになります。 同様に、CLI の設計が一般的なパターンに従っている場合、コマンド ライン アプリのユーザーのエクスペリエンスが向上します。

CLI を作成すると、特にユーザーが実行し続ける必要があるスクリプトで CLI を使用している場合は、変更が困難になります。 ここでのガイドラインは .NET CLI の後に開発されており、これらのガイドラインに必ずしも従っているわけではありません。 破壊的変更を導入することなく、.NET CLI を更新しています。 この作業の例として、.NET 7 の dotnet new の新しい設計があります。

シンボル

コマンドとサブコマンド

コマンドにサブコマンドがある場合、コマンドは、アクションを指定するのではなく、サブコマンドのエリアまたはグループ化 ID として機能する必要があります。 アプリを呼び出すときは、グループ化コマンドとそのサブコマンドの 1 つを指定します。 たとえば、dotnet toolを実行しようとすると、toolやinstallなどのツール関連のサブコマンドのグループのみがlist コマンドによって識別されるため、エラー メッセージが表示されます。 dotnet tool installを実行できますが、単独でdotnet toolは不完全です。

領域を定義してユーザーを支援する方法の 1 つは、ヘルプ出力を整理することです。

CLI 内には、多くの場合、暗黙的な領域があります。 たとえば、.NET CLI では、暗黙的な領域はプロジェクトであり、Docker CLI ではイメージです。 その結果、領域を含めずに dotnet build を使用できます。 CLI に暗黙的な領域があるかどうかを検討します。 その場合は、 docker build や docker image buildのように、ユーザーが必要に応じて含めるか省略するかを検討します。 必要に応じて、ユーザーが暗黙的な領域を入力できるようにする場合は、このコマンドグループのヘルプとタブ補完も自動的に行われます。 同じ操作を実行する 2 つのコマンドを定義して、暗黙的なグループのオプションの使用を指定します。

パラメーターとしてのオプション

オプションでは、アクション自体を指定するのではなく、コマンドにパラメーターを指定する必要があります。 これは推奨される設計原則ですが、常に System.CommandLine が続くわけではありません (ヘルプ情報が表示--help )。

名前付け

短い形式のエイリアス

一般に、定義する短い形式のオプションエイリアスの数は最小限にすることをお勧めします。

特に、.NET CLI やその他の .NET コマンド ライン アプリでの一般的な使用方法とは異なる方法で次のエイリアスを使用しないでください。

• -i (--interactive)。

  このオプションは、コマンドが回答する必要がある質問への入力を求められる可能性があることをユーザーに通知します。 たとえば、ユーザー名の入力を求めるメッセージが表示されます。 CLI はスクリプトで使用される可能性があるため、このスイッチを指定していないユーザーにメッセージを表示する場合は注意が必要です。

• -o (--output)。

  一部のコマンドでは、実行の結果としてファイルが生成されます。 このオプションは、これらのファイルが配置される場所を決定するために使用する必要があります。 1 つのファイルが作成される場合、このオプションはファイル パスにする必要があります。 多くのファイルが作成される場合、このオプションはディレクトリ パスにする必要があります。

• -v (--verbosity)。

  多くの場合、コマンドはコンソールでユーザーに出力を提供します。このオプションは、ユーザーが要求する出力の量を指定するために使用されます。 詳細については、この記事で後述 する「 --verbosity オプション 」を参照してください。

.NET CLI に限定された一般的な使用方法を持つエイリアスもあります。 これらのエイリアスは、アプリ内の他のオプションに使用できますが、混乱の可能性に注意してください。

• -c (--configuration)

  このオプションは、多くの場合、 Debug や Releaseなど、名前付きのビルド構成を参照します。 構成には任意の名前を使用できますが、ほとんどのツールではその 1 つが必要です。 この設定は、多くの場合、その構成に適した方法で他のプロパティを構成するために使用されます。たとえば、 Debug 構成を構築するときにコードの最適化を減らします。 コマンドの操作モードが異なる場合は、このオプションを検討してください。

• -f (--framework)

  このオプションは、実行する 1 つの ターゲット フレームワーク モニカー (TFM) を選択するために使用されます。そのため、選択した TFM に基づいて CLI アプリケーションの動作が異なる場合は、このフラグをサポートする必要があります。

• -p (--property)

  アプリケーションが最終的に MSBuild を呼び出す場合、多くの場合、ユーザーはその呼び出しを何らかの方法でカスタマイズする必要があります。 このオプションを使用すると、コマンド ラインで MSBuild プロパティを指定し、基になる MSBuild 呼び出しに渡すことができます。 アプリで MSBuild を使用せず、キーと値のペアのセットが必要な場合は、この同じオプション名を使用してユーザーの期待を活用することを検討してください。

• -r (--runtime)

  アプリケーションが異なるランタイムで実行できる場合、またはランタイム固有のロジックがある場合は、 ランタイム識別子を指定する方法としてこのオプションをサポートすることを検討してください。 アプリが --runtimeをサポートしている場合は、 --os のサポートと --arch も検討してください。 これらのオプションを使用すると、OS または RID のアーキテクチャ部分のみを指定でき、指定されていない部分は現在のプラットフォームから決定されます。 詳細については、「dotnet publish」を参照してください。

短い名前

コマンド、オプション、引数の名前をできるだけ短く簡単に入力します。 たとえば、 class が十分に明確な場合は、コマンドを classificationしないでください。

小文字の名前

名前は小文字のみで定義します。ただし、大文字のエイリアスを使用してコマンドやオプションの大文字と小文字を区別することはできません。

ケバブ ケースの名前

単語を区別するにはkebab ケースを使用します。 たとえば、--additional-probing-path のようにします。

複数化

アプリ内では、複数形化で一貫性を保つ。 たとえば、複数の値を持つオプション (最大アリティが 1 より大きい) には、複数形と単数形の名前を混在させないでください。

動詞と名詞

アクションを参照するコマンド (その下にサブコマンドがないコマンド) には、名詞ではなく動詞を使用します (たとえば、dotnet workload removeではなく、dotnet workload removal)。 オプションには動詞ではなく名詞を使用します。たとえば、--configurationではなく--configureします。

--verbosity オプション

System.CommandLine アプリケーションは、通常、コンソールに送信される出力量を指定する --verbosity オプションを提供します。 標準の 5 つの設定を次に示します。

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

これらは標準名ですが、既存のアプリでは、Silentの代わりにQuietを使用したり、Traceの代わりにDebug、Verbose、またはDiagnosticを使用したりする場合があります。

各アプリは、各レベルで表示される内容を決定する独自の条件を定義します。 通常、アプリには次の 3 つのレベルのみが必要です。

• 静か
• 正常
• 診断

アプリに 5 つの異なるレベルが必要ない場合でも、このオプションでは同じ 5 つの設定を定義する必要があります。 その場合、 Minimal と Normal は同じ出力を生成し、 Detailed と Diagnostic も同様に同じになります。 これにより、ユーザーは慣れているものを入力するだけで、最適なものが使用されます。

Quietの期待は、コンソールに出力が表示されないということです。 ただし、アプリが対話型モードを提供する場合、アプリは次のいずれかを実行する必要があります。

• --interactiveが--verbosityされている場合でも、Quietが指定されている場合は、入力のプロンプトを表示します。
• --verbosity Quietと--interactiveの併用を禁止します。

それ以外の場合、アプリはユーザーに何を待っているかを伝えずに入力を待機します。 アプリケーションがフリーズしているように見え、ユーザーはアプリケーションが入力を待機していることを知らなくなります。

エイリアスを定義する場合は、-vに--verbosityを使用し、引数を指定せずに-vを--verbosity Diagnosticのエイリアスにします。 -qには--verbosity Quietを使用します。

.NET CLI と POSIX の規則

.NET CLI は、すべての POSIX 規則に一貫して従うわけではありません。

二重ダッシュ

.NET CLI のいくつかのコマンドには、二重ダッシュ トークンの特別な実装があります。 dotnet run、dotnet watch、およびdotnet tool runの場合、--に続くトークンは、コマンドによって実行されているアプリに渡されます。 例えば次が挙げられます。

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

この例では、 --project オプションが dotnet run コマンドに渡され、引数を持つ --message オプションが実行時にコマンド ライン オプションとして myapp に渡されます。

-- トークンは、dotnet runを使用して実行するアプリにオプションを渡すために必ずしも必要であるとは限りません。 二重ダッシュを使用しない場合、 dotnet run コマンドは、 dotnet run 自体または MSBuild に適用されていると認識されないオプションを実行しているアプリに自動的に渡されます。 したがって、次のコマンド ラインは、 dotnet run が引数とオプションを認識しないため、同等です。

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

オプションから引数への区切り記号の省略

.NET CLI では、1 文字のオプション エイリアスを指定するときに区切り記号を省略できる POSIX 規則はサポートされていません。

オプション名を繰り返さない複数の引数

.NET CLI では、オプション名を繰り返さずに、1 つのオプションに対して複数の引数を受け入れることはできません。

ブール値のオプション

.NET CLI では、一部のブール型オプションは、falseを渡すときとtrueを渡すときと同じ動作になります。 この動作は、オプションを実装する .NET CLI コードがオプションの有無のみをチェックし、値を無視した場合に発生します。 たとえば、--no-restore コマンドのdotnet buildです。 --no-restore false渡すと、復元操作は、--no-restore trueまたは--no-restoreを指定した場合と同じようにスキップされます。

ケバブ ケース

場合によっては、.NET CLI でコマンド名、オプション名、または引数名に kebab case が使用されない場合があります。 たとえば、--additionalprobingpathではなく、--additional-probing-pathという名前の .NET CLI オプションがあります。

こちらも参照ください

• オープン ソースの CLI 設計ガイダンス
• GNU 標準