System.CommandLine でコマンド、オプション、引数を定義する方法

[アーティクル]
05/25/2023

重要

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

この記事では、System.CommandLine ライブラリを使って構築したコマンドラインアプリでコマンド、オプション、引数を定義する方法について説明します。これらの手法を示す完全なアプリケーションを構築する場合は、System.CommandLine の概要に関するチュートリアルを参照してください。

コマンドラインアプリのコマンド、オプション、引数の設計方法のガイダンスについては、設計ガイダンスのページを参照してください。

ルートコマンドを定義する

すべてのコマンドラインアプリにはルートコマンドがあります。これは実行可能ファイルそのものを指します。サブコマンド、オプション、引数がないアプリの場合、コードを呼び出す最も簡単なケースは、次のようになります。

using System.CommandLine;

class Program
{
    static async Task Main(string[] args)
    {
        var rootCommand = new RootCommand("Sample command-line app");

        rootCommand.SetHandler(() =>
        {
            Console.WriteLine("Hello world!");
        });

        await rootCommand.InvokeAsync(args);
    }
}

サブコマンドを定義する

コマンドは "サブコマンド" または "動詞" と呼ばれる子コマンドを含めることができます。また、必要な数だけ入れ子にすることができます。次の例のようにサブコマンドを追加できます。

var rootCommand = new RootCommand();
var sub1Command = new Command("sub1", "First-level subcommand");
rootCommand.Add(sub1Command);
var sub1aCommand = new Command("sub1a", "Second level subcommand");
sub1Command.Add(sub1aCommand);

この例の一番内側のサブコマンドは次のように呼び出すことができます。

myapp sub1 sub1a

オプションを定義する

通常、コマンドハンドラーメソッドにはパラメーターがあります。その値はコマンドラインオプションから取得できます。次の例では、2 つのオプションを作成し、ルートコマンドに追加しています。オプション名には、POSIX CLI に一般的な二重ハイフンプレフィックスが含まれています。コマンドハンドラーコードを使うと、これらのオプションの値を表示できます。

var delayOption = new Option<int>
    (name: "--delay",
    description: "An option whose argument is parsed as an int.",
    getDefaultValue: () => 42);
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.Add(delayOption);
rootCommand.Add(messageOption);

rootCommand.SetHandler((delayOptionValue, messageOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
        Console.WriteLine($"--message = {messageOptionValue}");
    },
    delayOption, messageOption);

前述のサンプルコードに対するコマンドライン入力とその結果の出力の例を次に示します。

myapp --delay 21 --message "Hello world!"

--delay = 21
--message = Hello world!

グローバルなオプション

一度に 1 つのコマンドにオプションを追加するには、前の例に示すように Add または AddOption メソッドを使います。あるコマンドにオプションを追加し、そのサブコマンドすべてに再帰的にオプションを追加するには、次の例に示すように AddGlobalOption メソッドを使います。

var delayOption = new Option<int>
    ("--delay", "An option whose argument is parsed as an int.");
var messageOption = new Option<string>
    ("--message", "An option whose argument is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.AddGlobalOption(delayOption);
rootCommand.Add(messageOption);

var subCommand1 = new Command("sub1", "First level subcommand");
rootCommand.Add(subCommand1);

var subCommand1a = new Command("sub1a", "Second level subcommand");
subCommand1.Add(subCommand1a);

subCommand1a.SetHandler((delayOptionValue) =>
    {
        Console.WriteLine($"--delay = {delayOptionValue}");
    },
    delayOption);

await rootCommand.InvokeAsync(args);

前述のコードでは、ルートコマンドにグローバルオプションとして --delay を追加し、subCommand1a のハンドラーで使用できるようにしています。

引数を定義する

引数を定義して、オプションのようにコマンドに追加します。次の例は、オプションの例と同じですが、オプションではなく引数を定義しています。

var delayArgument = new Argument<int>
    (name: "delay",
    description: "An argument that is parsed as an int.",
    getDefaultValue: () => 42);
var messageArgument = new Argument<string>
    ("message", "An argument that is parsed as a string.");

var rootCommand = new RootCommand();
rootCommand.Add(delayArgument);
rootCommand.Add(messageArgument);

rootCommand.SetHandler((delayArgumentValue, messageArgumentValue) =>
    {
        Console.WriteLine($"<delay> argument = {delayArgumentValue}");
        Console.WriteLine($"<message> argument = {messageArgumentValue}");
    },
    delayArgument, messageArgument);

await rootCommand.InvokeAsync(args);

前述のサンプルコードに対するコマンドライン入力とその結果の出力の例を次に示します。

myapp 42 "Hello world!"

<delay> argument = 42
<message> argument = Hello world!

前述の例の messageArgument のように、既定値なしで定義した引数は、必須の引数として扱われます。必須の引数を指定しない場合、エラーメッセージが表示され、コマンドハンドラーは呼び出されません。

別名を定義する

コマンドとオプションの両方が別名をサポートしています。 AddAlias を呼び出すことで、オプションに別名を追加できます。

var option = new Option("--framework");
option.AddAlias("-f");

この別名を指定しているので、次のコマンドラインは同等のものです。

myapp -f net6.0
myapp --framework net6.0

コマンドの別名も同じように機能します。

var command = new Command("serialize");
command.AddAlias("serialise");

このコードにより、次のコマンドラインは同等になります。

myapp serialize
myapp serialise

オプションの別名の定義は最小限に抑え、特に、特定の別名の定義は避けることをお勧めします。詳細については、「短い形式の別名」を参照してください。

必須オプション

オプションを必須にするには、次の例に示すように、その IsRequired プロパティを true に設定します。

var endpointOption = new Option<Uri>("--endpoint") { IsRequired = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

コマンドヘルプのオプションセクションに、このオプションが必須であることが表示されます。

Options:
  --endpoint <uri> (REQUIRED)
  --version               Show version information
  -?, -h, --help          Show help and usage information

このサンプルアプリのコマンドラインに --endpoint が含まれていない場合は、エラーメッセージが表示され、コマンドハンドラーは呼び出されません。

Option '--endpoint' is required.

必須オプションに既定値がある場合は、コマンドラインでオプションを指定する必要はありません。その場合、既定値によって必須オプションの値が提供されます。

非表示のコマンド、オプション、引数

あるコマンド、オプション、引数をサポートはしても、それが簡単に見つからないようにしたい場合があります。たとえば、非推奨、管理用、プレビューの機能などです。次の例に示すように、IsHidden プロパティを使うと、ユーザーはタブ補完やヘルプを使ってその機能を見つけられなくなります。

var endpointOption = new Option<Uri>("--endpoint") { IsHidden = true };
var command = new RootCommand();
command.Add(endpointOption);

command.SetHandler((uri) =>
    {
        Console.WriteLine(uri?.GetType());
        Console.WriteLine(uri?.ToString());
    },
    endpointOption);

await command.InvokeAsync(args);

この例のコマンドヘルプのオプションセクションでは、--endpoint オプションが省略されます。

Options:
  --version               Show version information
  -?, -h, --help          Show help and usage information

引数のアリティ (個数) を設定する

Arity プロパティを使うことで引数のアリティを明示的に設定できますが、ほとんどの場合は必要ありません。 System.CommandLine により、引数の型に基づいて引数のアリティが自動的に決定されます。

引数の型	既定のアリティ
`Boolean`	`ArgumentArity.ZeroOrOne`
コレクション型	`ArgumentArity.ZeroOrMore`
その他すべて	`ArgumentArity.ExactlyOne`

複数の引数

既定では、コマンドを呼び出すときにオプション名を繰り返し指定することで、最大アリティが 1 より大きいオプションに対して複数の引数を指定できます。ことができます。

myapp --items one --items two --items three

オプション名を繰り返さずに複数の引数を指定するには、Option.AllowMultipleArgumentsPerToken を true に設定します。この設定を使うと、次のようなコマンドラインを入力できます。

myapp --items one two three

同じ設定でも、最大引数アリティが 1 の場合は、効果が異なります。この場合、オプションを繰り返しても、その行の最後の値のみを受け取ることができます。次の例では、値 three がアプリに渡されます。

myapp --item one --item two --item three

有効な引数値を一覧表示する

オプションまたは引数の有効な値の一覧を指定するには、次の例に示すように、オプションの型として enum を指定するか、FromAmong を使います。

var languageOption = new Option<string>(
    "--language",
    "An option that that must be one of the values of a static list.")
        .FromAmong(
            "csharp",
            "fsharp",
            "vb",
            "pwsh",
            "sql");

前述のサンプルコードに対するコマンドライン入力とその結果の出力の例を次に示します。

myapp --language not-a-language

Argument 'not-a-language' not recognized. Must be one of:
        'csharp'
        'fsharp'
        'vb'
        'pwsh'
        'sql'

コマンドヘルプのオプションセクションに、有効な値が表示されます。

Options:
  --language <csharp|fsharp|vb|pwsh|sql>  An option that must be one of the values of a static list.
  --version                               Show version information
  -?, -h, --help                          Show help and usage information

オプションと引数の検証

引数の検証とそのカスタマイズ方法については、パラメーターバインドに関する記事の以下のセクションを参照してください。

System.CommandLine でコマンド、オプション、引数を定義する方法

ルートコマンドを定義する

サブコマンドを定義する

オプションを定義する

グローバルなオプション

引数を定義する

別名を定義する

必須オプション

非表示のコマンド、オプション、引数

引数のアリティ (個数) を設定する

複数の引数

有効な引数値を一覧表示する

オプションと引数の検証

関連項目

フィードバック

その他のリソース

System.CommandLine でコマンド、オプション、引数を定義する方法

ルート コマンドを定義する

サブコマンドを定義する

オプションを定義する

グローバルなオプション

引数を定義する

別名を定義する

必須オプション

非表示のコマンド、オプション、引数

引数のアリティ (個数) を設定する

複数の引数

有効な引数値を一覧表示する

オプションと引数の検証

関連項目

フィードバック

その他のリソース

ルートコマンドを定義する