Add --name option
Now that we can invoke a command we can add a simple option. In this case we will add the option --name
which we will use to optionally customize the message we output. Add the following to Program.cs
.
rootCommand.Add(new Option("--name", description: "Name of person to greet"));
If we now run dotnet run -- --help
we can see that the option is now available. However, since we hav
$ dotnet run -- --help
SimpleCmdLine
Console app to demonstrate System.CommandLine
Usage:
SimpleCmdLine [options]
Options:
--name Name of person to greet
--version Show version information
-?, -h, --help Show help and usage information
$
If we execute the application without the option we still get the expected output. If we add the --name
option we also get the same output. This is expected since we didn't make any changes to actually use the option.
If we provide a parameter to the --name
option however we get an error.
$ dotnet run
Hello World!
$ dotnet run -- --name
Hello World!
$ dotnet run -- --name Me
'Me' was not matched. Did you mean '-h'?
Unrecognized command or argument 'Me'
SimpleCmdLine
Console app to demonstrate System.CommandLine
Usage:
SimpleCmdLine [options]
Options:
--name Name of person to greet
--version Show version information
-?, -h, --help Show help and usage information
$
We added the command to the rootCommand so why does it not recognize the parameter to it?
In order for the parameter to be passed to the RootCmd()
method we need to add it to the method.
public static void RootCmd(string name = "World")
{
Console.WriteLine($"Hello {name}!");
}
Now that we have added the parameter to the method signature what happens when we run the application?
$ dotnet run -- --name Me
'Me' was not matched. Did you mean '-h'?
Unrecognized command or argument 'Me'
We seem to still get the same result. The answer as to why is in the way that we declared the options.
When we declared the option we did not tell it what type of option it is. When declared without a type the option acts as an option without any parameters. A common option that might act like this would be --verbose
. When this option is used it does not require any additional parameters.
Since we want to be able to pass a string as a parameter to the --name
option we need to change how we declare the option.
rootCommand.Add(new Option<string>("--name", description: "Name of person to greet"));
Now if we run the application we can see how the changes have affected how it works.
$ dotnet run
Hello World!
$ dotnet run -- --name
Required argument missing for option: --name
SimpleCmdLine
Console app to demonstrate System.CommandLine
Usage:
SimpleCmdLine [options]
Options:
--name <name> Name of person to greet
--version Show version information
-?, -h, --help Show help and usage information
$ dotnet run -- --name Me
Hello Me!
$
The help output now indicates that a <name>
parameter is to be provided and it no longer complains about 'Me' not being a valid command argument.
Making an command required
What if we want to force an option to be required? We can do this by using the IsRequired property of the option.
rootCommand.Add(new Option<string>("--name", description: "Name of person to greet") { IsRequired=true});
If we try to execute the application without providing the name we now get notified that it is required.
$ dotnet run
Option '--name' is required.
SimpleCmdLine
Console app to demonstrate System.CommandLine
Usage:
SimpleCmdLine [options]
Options:
--name <name> (REQUIRED) Name of person to greet
--version Show version information
-?, -h, --help Show help and usage information
$ dotnet run -- --name You
Hello You!
You must be logged in to see the comments. Log in now!