System.CommandLine のコマンド ライン構文の概要

  • [アーティクル]

重要

System.CommandLine は現在プレビュー段階であり、このドキュメントはバージョン 2.0 beta 4 を対象としています。 一部の情報は、リリース前に大きく変更される可能性があるプレリリースされた製品に関するものです。 Microsoft は、ここに記載されている情報について、明示または黙示を問わず、一切保証しません。

この記事では、System.CommandLine で認識されるコマンド ライン構文について説明します。 この情報は、.NET CLI を含む .NET コマンド ライン アプリの開発者だけでなく、ユーザーにとっても役立ちます。

トークン

System.CommandLine は、コマンド ライン入力を解析して、スペースで区切られた文字列である "トークン" を生成します。 例として、次のようなコマンド ラインを考えてみます。

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

この入力は dotnet アプリケーションによって解析され、トークン tool、install、dotnet-suggest、--global、--verbosity、quiet が生成されます。

トークンは、コマンド、オプション、または引数として解釈されます。 呼び出されているコマンド ライン アプリによって、最初のもの以降のトークンの解釈方法が決定されます。 次の表は、System.CommandLine によって上記の例がどのように解釈されるかを示しています。

トークン 解析結果
tool サブコマンド
install サブコマンド
dotnet-suggest install コマンドの引数
--global install コマンドのオプション
--verbosity install コマンドのオプション
quiet --verbosity オプションの引数

トークンが引用符 (") で囲まれている場合、トークンにスペースを含めることができます。 次に例を示します。

dotnet tool search "ef migrations add"

コマンド

コマンド ライン入力の "コマンド" とは、アクションを指定する、または関連するアクションのグループを定義するトークンです。 次に例を示します。

  • dotnet run の run は、アクションを指定するコマンドです。
  • dotnet tool install の install はアクションを指定するコマンドであり、tool は関連するコマンドのグループを指定するコマンドです。 tool uninstall、tool list、tool update など、tool に関連するコマンドは他にもあります。

ルート コマンド

"ルート コマンド" は、アプリの実行可能ファイルの名前を指定するコマンドです。 たとえば、dotnet コマンドは、dotnet.exe という実行可能ファイルを指定します。

サブコマンド

ほとんどのコマンド ライン アプリでは、"サブコマンド" がサポートされています ("動詞" とも呼ばれます)。 たとえば、dotnet コマンドには run というサブコマンドがあり、dotnet run と入力して呼び出すことができます。

サブコマンドは、独自のサブコマンドを持つことができます。 dotnet tool install の install は、tool のサブコマンドです。

オプション

オプションとは、コマンドに渡すことができる名前付きパラメーターです。 POSIX CLI は通常、オプション名の前に 2 つのハイフン (--) を付けます。 次の例は、2 つのオプションを示しています。

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

この例に示すように、オプションの値は明示的 (--verbosity の quiet)、または暗黙的 (--global の後には何も続かない) に指定できます。 通常、値が指定されないオプションはブール値のパラメーターであり、コマンド ラインでそのオプションが指定される場合、既定値は true になります。

一部の Windows コマンド ライン アプリでは、オプション名の先頭にスラッシュ (/) を使用してオプションを識別します。 次に例を示します。

msbuild /version
        ^------^

System.CommandLine では、POSIX と Windows 両方のプレフィックス規則がサポートされています。 オプションを構成する場合は、プレフィックスを含むオプション名を指定します。

引数

引数とは、オプションまたはコマンドに渡される値です。 次の例は、verbosity オプションの引数と、build コマンドの引数を示しています。

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

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

引数は、引数が明示的に指定されない場合に適用される既定値を持つことができます。 たとえば、多くのオプションは、そのオプション名がコマンド ライン内で使用されるとき、暗黙的に既定値 true を持つブール値パラメーターになります。 次の各コマンド ライン例は等価です。

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

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

一部のオプションには必須の引数があります。 たとえば、.NET CLI では、--output にはフォルダー名の引数が必要です。 引数が指定されていない場合、コマンドは失敗します。

引数は想定される型を持つことができます。引数を想定される型に解析できない場合は、System.CommandLine によりエラー メッセージが表示されます。 たとえば、次のコマンドを実行するとエラーが発生します。"silent" は --verbosity の有効な値の 1 つではないためです。

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

引数では、指定できる値の数も想定されます。 例については、引数のアリティに関するセクションを参照してください。

オプションと引数の順序

コマンド ラインでは、引数の前にオプションを指定しても、オプションの前に引数を指定しても構いません。 次の各コマンドは等価です。

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

オプションは任意の順序で指定できます。 次の各コマンドは等価です。

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

複数の引数がある場合は、順序が重要になります。 次の各コマンドは、必ずしも等価ではありません。

myapp argument1 argument2
myapp argument2 argument1

これらのコマンドは、同じ値を持つリストをコマンド ハンドラー コードに渡しますが、値の順序が異なるため、異なる結果になる場合があります。

エイリアス

POSIX と Windows の両方において、一部のコマンドやオプションがエイリアスを持つことは一般的です。 通常、それらは入力しやすい短い形式です。 別名は、大文字と小文字の区別をシミュレートしたり、単語の代替スペルをサポートしたりするなど、他の目的にも使用できます。

典型的な POSIX の短い形式は、先頭にハイフンが 1 つ、その後に 1 文字が続くものです。 次の各コマンドは等価です。

dotnet build --verbosity quiet
dotnet build -v quiet

GNU 標準では、自動エイリアスが推奨されています。 つまり、長い形式のコマンド名やオプション名の任意の部分を入力すれば、それが受け入れられます。 この動作により、次の各コマンド ラインは等価になります。

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 では、自動エイリアスはサポートされていません。

大文字小文字の区別

コマンド名、オプション名とエイリアスは、POSIX 規則に従って既定で大文字と小文字が区別され、System.CommandLine はこの規則に従います。 CLI で大文字と小文字を区別しないようにするには、さまざまな大文字と小文字を使用した代替のエイリアスを定義します。 たとえば、--additional-probing-path は --Additional-Probing-Path や --ADDITIONAL-PROBING-PATH というエイリアスを持つことができます。

一部のコマンド ライン ツールでは、大文字と小文字の違いによって機能の違いが指定されます。 たとえば、git clean -X の動作は git clean -x とは異なります。 .NET CLI はすべて小文字です。

列挙型に基づくオプションの引数値には、大文字と小文字の区別は適用されません。 列挙型名は、大文字と小文字に関係なく照合されます。

-- トークン

POSIX 規則では、二重ダッシュ (--) トークンはエスケープ メカニズムとして解釈されます。 二重ダッシュ トークンの後に続くものはすべて、コマンドの引数として解釈されます。 この機能を使うと、オプションのように見える引数を指定できます。これによりオプションとして解釈されなくなるためです。

たとえば、myapp は message 引数を受け取り、message の値を --interactive にしたいとします。 次のコマンド ラインを実行すると、予期しない結果が発生するおそれがあります。

myapp --interactive

myapp に --interactive というオプションがなければ、--interactive トークンは引数として解釈されます。 しかし、このアプリに --interactive オプションがあった場合、この入力はそのオプションを指していると解釈されます。

次のコマンド ラインでは、二重ダッシュ トークンを使って、message 引数の値を "--interactive" に設定しています。

myapp -- --interactive
      ^^

System.CommandLine では、この二重ダッシュの機能がサポートされています。

オプションと引数の区切り記号

System.CommandLine では、オプション名とその引数の間の区切り記号として、スペース、'='、または ':' を使用できます。 たとえば、次の各コマンドは等価です。

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

POSIX 規則では、1 文字のオプションのエイリアスを指定するときに区切り記号を省略できます。 たとえば、次の各コマンドは等価です。

myapp -vquiet
myapp -v quiet

System.CommandLine では、この構文が既定でサポートされています。

引数のアリティ

オプションやコマンドの引数の "アリティ" とは、そのオプションやコマンドを指定する場合に渡すことができる値の数です。

次の表に示すように、アリティは最小値と最大値で表されます。

Min Max 例の有効性 例
0 0 有効: --file
無効: --file a.json
無効: --file a.json --file b.json
0 1 有効: --flag
有効: --flag true
有効: --flag false
無効: --flag false --flag false
1 1 有効: --file a.json
無効: --file
無効: --file a.json --file b.json
0 n 有効: --file
有効: --file a.json
有効: --file a.json --file b.json
1 n 有効: --file a.json
有効: --file a.json b.json
無効: --file

System.CommandLine には、アリティを定義するための ArgumentArity 構造体があり、次の値が含まれます。

  • Zero - 値は許可されません。
  • ZeroOrOne - 1 つの値を持つか、値を持たないことができます。
  • ExactlyOne - 1 つの値を持つ必要があります。
  • ZeroOrMore - 1 つの値または複数の値を持つか、値を持たないことができます。
  • OneOrMore - 複数の値を持つことができ、少なくとも 1 つの値を持つ必要があります。

多くの場合、アリティは型から推論できます。 たとえば、int オプションのアリティは ExactlyOne、List<int> オプションのアリティは OneOrMore です。

オプションのオーバーライド

アリティの最大値が 1 の場合でも、オプションの複数のインスタンスを受け入れるように System.CommandLine を構成できます。 その場合、繰り返されたオプションの最後のインスタンスによって、それより前のインスタンスが上書きされます。 次の例では、値 2 が myapp コマンドに渡されます。

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

複数の引数

アリティの最大値が 1 より大きい場合は、オプション名を繰り返さずに、1 つのオプションに対して複数の引数を受け入れるように System.CommandLine を構成できます。

次の例では、コマンド myapp に渡されるリストには "a"、"b"、"c"、"d" が含まれます。

myapp --list a b c --list d

オプションのバンドル

POSIX では、1 文字のオプションの "バンドル" ("スタック" とも呼ばれます) をサポートすることが推奨されています。 バンドルされたオプションは、1 つのハイフン プレフィックスの後に、1 文字のオプション エイリアスをまとめて指定したものです。 引数を指定できるのは、最後のオプションのみです。 たとえば、次の各コマンド ラインは等価です。

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

オプション バンドルの後に引数が指定された場合は、バンドル内の最後のオプションに適用されます。 次のコマンド ラインは同等のものです。

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

この例の両方のバリアントでは、引数 arg はオプション -c にのみ適用されます。

ブール値のオプション (フラグ)

bool 引数を持つオプションに対して true または false が渡された場合は、想定どおりに解析されます。 しかし、通常、引数の型が bool であるオプションには、引数を指定する必要はありません。 通常、ブール値のオプション ("フラグ" と呼ばれることもあります) のアリティは、ZeroOrOne です。 コマンド ライン上にそのオプション名が存在し、その後に引数がない場合、既定値は true になります。 コマンド ライン入力にそのオプション名がない場合、値は false になります。 myapp コマンドによって --interactive という名前のブール値オプションの値が出力される場合、次の入力を指定すると以下のような出力が生成されます。

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

False
True
False
True

--help オプション

コマンド ライン アプリには、通常、使用できるコマンド、オプション、引数の簡単な説明を表示するためのオプションが用意されています。 System.CommandLine では自動的にヘルプ出力が生成されます。 次に例を示します。

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.

アプリのユーザーは、各種プラットフォームでヘルプを要求するためのさまざまな方法に慣れている可能性があります。そのため、System.CommandLine に基づいて構築されたアプリは、ヘルプを要求するさまざまな方法に対応できます。 次の各コマンドはすべて等価です。

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

ヘルプ出力では、使用できるすべてのコマンド、引数、オプションが必ずしも表示されるとは限りません。 その一部は "非表示" になる場合があります。つまり、ヘルプ出力には表示されませんが、コマンド ラインで指定できます。

--version オプション

System.CommandLine に基づいて構築されたアプリは、ルート コマンドと共に --version オプションを使うと、応答として自動的にバージョン番号を返します。 次に例を示します。

dotnet --version

6.0.100

応答ファイル

"応答ファイル" とは、コマンド ライン アプリのトークンのセットを含むファイルです。 応答ファイルは、次の 2 つのシナリオで役立つ System.CommandLine の機能です。

  • ターミナルの文字数制限より長い入力を指定してコマンド ライン アプリを起動する。
  • 行全体を再入力せずに、同じコマンドを繰り返し呼び出す。

応答ファイルを使用するには、行内でコマンド、オプション、引数を挿入したい任意の場所に、先頭に @ 記号を付けたファイル名を入力します。 .rsp ファイル拡張子が一般的な規則ですが、任意のファイル拡張子を使用できます。

次の行は等価です。

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

sample1.rsp の内容:

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

sample2.rsp の内容:

--no-restore

応答ファイル内のテキストの解釈方法を決定する構文規則を次に示します。

  • トークンはスペースで区切られます。 Good morning! を含む行は、2 つのトークン Good と morning! として扱われます。
  • 引用符で囲まれた複数のトークンは、1 つのトークンとして解釈されます。 "Good morning!" を含む行は 1 つのトークン Good morning! として扱われます。
  • # 記号から行末までのテキストはコメントとして扱われ、無視されます。
  • プレフィックス @ が付いたトークンは、追加の応答ファイルを参照できます。
  • 応答ファイルには、複数行のテキストを含めることができます。 行は連結され、一連のトークンとして解釈されます。

ディレクティブ

System.CommandLine では、"ディレクティブ" と呼ばれる構文要素が導入されています。 [parse] ディレクティブはその一例です。 アプリ名の後に [parse] を含めると、System.CommandLine によって、コマンド ライン アプリを呼び出す代わりに、解析結果を示す図が表示されます。

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

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

ディレクティブの目的は、各コマンド ライン アプリにまたがって適用できる横断的な機能を提供することです。 ディレクティブは、アプリ独自の構文とは構文的に区別されるため、各アプリにまたがって適用される機能を提供できます。

ディレクティブは、次の構文規則に従う必要があります。

  • アプリ名の後、すべてのサブコマンドやオプションの前に指定する、コマンド ライン上のトークンである。
  • 角かっこで囲む。
  • スペースを含まない。

認識されないディレクティブは無視され、解析エラーが発生することはありません。

ディレクティブには引数を含めることができ、コロンによってディレクティブ名と区切ります。

次のディレクティブは組み込まれています。

[parse] ディレクティブ

指定した入力をアプリがどのように解釈するか確認できると、ユーザーと開発者のどちらにとっても便利なことがあります。 System.CommandLine アプリの既定の機能の 1 つに、[parse] ディレクティブがあります。これを使うと、コマンド入力の解析結果をプレビューできます。 次に例を示します。

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

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

前の例の場合:

  • コマンド (myapp)、その子オプション、それらのオプションに対する引数が、角かっこを使ってグループ化されます。
  • オプション結果 [ --delay !<not-an-int> ] について、! は解析エラーを示しています。 int オプションに対する値 not-an-int は、想定された型に解析できません。 エラーは、このエラー オプションが含まれるコマンドの前の ! によっても示されています: ![ myapp...。
  • オプション結果 *[ --fgcolor <White> ] については、このオプションがコマンド ラインで指定されていないため、構成された既定値が使用されました。 White は、このオプションに対する有効な値です。 アスタリスクは、値が既定値であることを示します。
  • ???--> は、アプリのいずれのコマンドやオプションにも一致しなかった入力を指します。

[suggest] ディレクティブ

[suggest] ディレクティブを使うと、正確なコマンドがわからないときに、そのコマンドを検索できます。

dotnet [suggest] buil

build
build-server
msbuild

設計ガイダンス

以下のセクションでは、CLI の設計時に従うことをお勧めするガイダンスを紹介します。 コマンド ラインでアプリが想定するものは、URL で REST API サーバーが想定するものと同じように考えることができます。 REST API の一貫性のある規則によって、クライアント アプリの開発者がそれらを簡単に使用できるようになります。 同様に、CLI の設計が共通のパターンに従っている場合、コマンド ライン アプリのユーザーのエクスペリエンスが向上します。

一度 CLI を作成した後は、変更することが難しくなります。ユーザーが既にスクリプトで CLI を使用していて、それを実行し続けることを想定している場合は、特にそうです。 ここに示すガイドラインは .NET CLI の後に開発されたものであり、これは常にこれらのガイドラインに従うわけではありません。 私たちは、破壊的変更を導入することなく更新できる場所で、.NET CLI を更新しています。 この作業の例として、.NET 7 の dotnet new の新しい設計が挙げられます。

コマンドとサブコマンド

コマンドがサブコマンドを持っている場合、そのコマンドはアクションを指定するのではなく、領域、またはそのサブコマンドのグループ化識別子として機能する必要があります。 アプリを起動する場合は、グループ化コマンドとそのサブコマンドの 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 に限定された共通の使用方法を持つエイリアスもあります。 アプリの他のオプション用にこれらのエイリアスを使うこともできますが、混乱を招く可能性があることに注意してください。

  • --configuration の -c

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

  • --framework の -f

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

  • --property の -p

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

  • --runtime の -r

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

短い名前

コマンド、オプション、引数の名前は、できるだけ短く、スペルが簡単になるようにしてください。 たとえば、class が十分に明確であれば、コマンド classification は作成しないでください。

小文字の名前

名前は小文字のみで定義します。ただし、大文字のエイリアスを作成して、コマンドやオプションの大文字と小文字が区別されないようにする場合は除きます。

ケバブ ケースの名前

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

複数形化

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

オプション名 一貫性
--additional-probing-paths および --sources ✔️
--additional-probing-path および --source ✔️
--additional-probing-paths および --source ❌
--additional-probing-path および --sources ❌

動詞と名詞

アクションを指し示すコマンド (サブコマンドを含まないコマンド) には、名詞ではなく動詞を使用します (例: dotnet workload removal ではなく dotnet workload remove)。 また、オプションに対しては動詞ではなく名詞を使用します (例: --configure ではなく --configuration)。

--verbosity オプション

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

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

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

各アプリによって、それぞれのレベルで表示される内容を決定する独自の基準が定義されます。 通常、アプリに必要なレベルは 3 つだけです。

  • Quiet
  • Normal
  • Diagnostic

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

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

  • --interactive が指定されている場合は、--verbosity が Quiet でも、入力を求めるメッセージを表示する。
  • --verbosity Quiet と --interactive を一緒に使用することを禁止する。

そうしないと、アプリはユーザーに何を待機しているか知らせずに、入力を待機することになります。 アプリケーションはフリーズしたように見え、アプリケーションが入力を待機していることがユーザーにはわかりません。

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

.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 コードが、オプションの有無をチェックするだけで、その値は無視する場合に発生します。 その例としては、dotnet build コマンドの --no-restore が挙げられます。 no-restore false を渡すと、no-restore true または no-restore を指定した場合と同じように、復元操作はスキップされます。

ケバブ ケース

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

こちらもご覧ください