ConsoleApp.CommandLine
1.3.1
See the version list below for details.
dotnet add package ConsoleApp.CommandLine --version 1.3.1
NuGet\Install-Package ConsoleApp.CommandLine -Version 1.3.1
<PackageReference Include="ConsoleApp.CommandLine" Version="1.3.1" />
paket add ConsoleApp.CommandLine --version 1.3.1
#r "nuget: ConsoleApp.CommandLine, 1.3.1"
// Install ConsoleApp.CommandLine as a Cake Addin #addin nuget:?package=ConsoleApp.CommandLine&version=1.3.1 // Install ConsoleApp.CommandLine as a Cake Tool #tool nuget:?package=ConsoleApp.CommandLine&version=1.3.1
Introduction
Tools for building console application.
Installation
Install-Package ConsoleApp.CommandLine
Quick Start
Basics
To start, you need to configure the entry point to the application. Where "ConsoleApp" will be your class with a command handler.
using System
class Program
{
public static int Main()
{
return CommandLine.Run<Program>(CommandLine.Arguments, defaultCommandName: "SayHello")
}
public static int SayHello()
{
Console.WriteLine("Hello!");
return 0;
}
}
CommandLine.Run relies on reflection to find methods. So they should be static and return int which is Exit Code
Now you can test your application:
myapp.exe SayHello
#>Hello!
myapp.exe SAYHELLO
#>Hello! -- command name is case-insensitive (parameters are not!)
myapp.exe
#>Hello! - Too because 'defaultCommandName' is set to 'SayHello'
Parameter bindings
Positional and named parameters
You can add parameters to your command which is automatically binds by name or position
public static int SayHello(string name)
{
Console.WriteLine("Hello " + name + "!");
return 0;
}
Testing:
myapp.exe SayHello Mike
#>Hello Mike!
myapp.exe SayHello --name Jake
#>Hello Jake!
List parameters
You can add array parameter to collect multiple values as shown below:
public static int SayHello(string[] names)
{
Console.WriteLine("Hello " + string.Join(", ", names) + "!");
return 0;
}
Testing:
myapp.exe SayHello --names Mike Jake
#>Hello Mike, Jake!
Parameter accepting multiple values can be only named.
Optional parameters
You can make any parameter optional by specifying default value.
public static int ShowOptionalParameter(int myOptionalParam = 100)
{
Console.WriteLine("My optional parameter is " + myOptionalParam);
return 0;
}
Testing:
myapp.exe ShowOptionalParameter --myOptionalParam 200
#>My optional parameter is 200
myapp.exe ShowOptionalParameter 300
#>My optional parameter is 300
myapp.exe ShowOptionalParameter
#>My optional parameter is 100
Flag parameters
You can have a flag(true/false) parameter. It's presence is considered to be "True" and absence is "False".
public static int ShowFlag(bool myFlag)
{
Console.WriteLine(myFlag ? "Flag is set" : "Flag is not set");
return 0;
}
Testing:
myapp.exe ShowFlag --myFlag
#>Flag is set
myapp.exe ShowFlag
#>Flag is not set
Parameters values starting with hyphen(-) symbol
Negative numbers (such as -1000) are interpreted as values by default. But strings like "-a", "-hello" are interpreted as named parameters. To stop this interpretation you could place bare hyphen:
myapp.exe - --message -hello --class -a
Enforcing positional parameters
You could pass bare double hyphen(--) and anything after it will be threated as positional parameters.
myapp.exe --type message -- value1 value2 value3
No special symbols are interpeted after double hyphen(--) even another double hypthen:
myapp.exe --type message -- -value1 --value2 --value3-- --
Supported Parameter Types
- Primitive types (int, byte, char ...)
- BCL types (String, DateTime, Decimal)
- Nullable types
- Enum types
- Types with TypeConverterAttribute (Point, Guid, Version, TimeSpan ...)
- Types with Parse(string value) method (IpAddress, Guid ...)
- Types with explicit/implicit conversion from string
Сommands Hierarchy
Suppose you want to build a complex API where commands are grouped by purpose.
Example:
myfinance.exe Account Show --id 0a0e0000000
Each group must be defined as method(command) with one CommandLineArguments argument.
public static int Account(CommandLineArguments arguments)
{
return CommandLine.Run<AccountCommands>(arguments);
}
class AccountCommands
{
public static int Show()
{
// ...
}
}
where AccountCommands is class with list of commands as described in "Basics".
Commands Description
Your command line application can generate help for the user. This requires to define Help method with following code inside
public static int Help()
{
return CommandLine.Describe<ConsoleApp>();
}
Testing:
myapp.exe Help
> HELP
Not too much information 😃
You can decorate the method with DescriptionAttribute attributes to expand 'Help' information.
using System.ComponentModel;
[Description("Display this help.")]
public static int Help()
{
return CommandLine.Describe<ConsoleApp>();
}
Testing:
myapp.exe Help
> HELP - Display this help.
You can add these attributes to the methods, parameters and classes. All of them are involved in the generation of reference.
Handling Errors
To catch and handle binding or execution errors you could subscribe on CommandLine.UnhandledException method.
CommandLine.UnhandledException += (sender, args) => Console.WriteLine(args.Exception.ToString());
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
| .NET Core | netcoreapp1.0 was computed. netcoreapp1.1 was computed. netcoreapp2.0 is compatible. netcoreapp2.1 is compatible. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard1.3 is compatible. netstandard1.4 was computed. netstandard1.5 was computed. netstandard1.6 was computed. netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net35 is compatible. net40 was computed. net403 was computed. net45 is compatible. net451 was computed. net452 was computed. net46 was computed. net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen30 was computed. tizen40 was computed. tizen60 was computed. |
| Universal Windows Platform | uap was computed. uap10.0 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETCoreApp 2.0
- No dependencies.
-
.NETCoreApp 2.1
- No dependencies.
-
.NETFramework 3.5
- No dependencies.
-
.NETFramework 4.5
- No dependencies.
-
.NETStandard 1.3
- NETStandard.Library (>= 1.6.1)
-
.NETStandard 2.0
- No dependencies.
NuGet packages (1)
Showing the top 1 NuGet packages that depend on ConsoleApp.CommandLine:
| Package | Downloads |
|---|---|
|
CodeContractsRemover
Package Description |
GitHub repositories
This package is not used by any popular GitHub repositories.
# 1.3.1
- TypeConvert dependecy update (bug fixes)
# 1.3.0
- added TypeConverterAttribute support on command parameters. It's takes precendence before any other types of type conversions.
# 1.2.9
- added netcoreapp2.1 target platform
- dependencies update (internal)
# 1.2.7
- fixed exception when calling Describe while console output is redirected
- TypeConvert package update
# 1.2.6
- TypeConvert package update
- documentation update
# 1.2.5
- added WriteWholeErrorMessageOnBindFailure option for debugging purpose (it writes descriptive error message to stderr stream)
- added DescribeExitCode option for controlling exit code of Describe method
- tuned error messages when no command is specified or wrong parameters are passed
- tuned Describe method for better description text (friendly type names, nullable types support etc...)
# 1.2.4
- fixed binding error when no default action is specified
- added XML documentation file to package
# 1.2.3
- updated references for .NET Core Targets and .NET Standard
# 1.2.2
- returned original library name ConsoleApp.CommandLine.dll
# 1.2.1
- embedded TypeConvert dependency
# 1.2.0
- CommandLine.UnhandledException type changed to ExceptionEventHandler
- added custom description attributes as replacement to System.ComponentModel attributes: HelpTextAttribute and HiddenAttribute
- added support of .NET Standard platform
# 1.1.3
- refactored error messages fo parameters binding failure cases.
- added CommandLineException to signal binding failures.
- fixed few array parameter binding bugs
# 1.1.2
- added bare double hyphen to enforce positional parameters
- added bare single hyphen to disable hyphen interpretation in values
- added special treatment for negative numbers
- added CommandLine.DescribeOnBindFailure which controls reaction on method binding failure (true to run CommandLine.Describe(), false to throw exception).
- added enum flags binding subroutine, now "--flag Flag1 Flag2 Flag3" arguments are supported.
- changed method binding order to from most parameters to less (original was chaotic), binding strategy is still - "first match".
- added non-generic Run and Describe methods
- fixed bug with positional parameters binding
# 1.0.0
- initial release