Today’s post is a look @ a nuget package that has been around for a while (2005 to be exact) & is still commanding respect in the developer community.
If you find yourself developing a command line application that requires various input, maybe for the purpose of automating a process on your continuous integration pipeline or perhaps its just for simple input to get data into a system, chances being if you are writing this from scratch you will have spent a bit of time trying to ensure the user input is parsed correctly, this can be time consuming right?
Well fear no more, the CommandLineParser library is here to the rescue. CommandLineParser is, err..as the name suggests, a command line parser for .NET. The API offers a nice array of features out of the box, one of the biggest ones being a help text guide for each of the inputs you specify which gives a bit of vavoom to your console app (not to mention relief for your end users).
A small example, we will create a console application that will display various command line parameter inputs to the screen. This kind of application without using the nuget package might be a bit time consuming, as you would need to validate the inputs, etc etc.
Downloading the package from nuget (currently @ v2 at time of writing this post), you create a class, lets call it UserOptions and create a series of properties that will represent your command line parameter inputs such as Id, Name & Hobbies. Next, you will add an attribute called Option above each of the properties as in the following screenshot (il explain this attribute further on):
Under the main method, apply the following API call like so
Both methods in the fluent calls, DisplayOptionsInputted & HandleParserError are displayed below – these are just methods that would perform the task required.
To see the application in action set the command line arguments like so in the project properties window & run the project:
And voila.. output to the console screen the inputs supplied from above:
If i pass in an unknown parameter like so:
This will trigger the .WithNotParsed() method to execute..the API out of the box will also display the Helper text as so (this can be overridden if required):
The Option attribute (set in the UserOptions class above) is one of the magic ingredients that will perform the out of the box validation for your parameters. In the above i have applied some of the basic properties that can be used.
Interesting properties to set are HelpText which will be displayed when user specifies the built in parameter –help, you also have different ways as to how you want the parameter parsed, for example if you want the input Name to be abbreviated to ‘n’ on the command line then you can do this by passing ‘n’ as per above. If you don’t specify this the field will default to its original property name. If a parameter is always needed as input then you can set it as Required=true, if you omit this parameter when running the app you will get error like following.. (specific error highlighted in yellow)
Pretty cool, right! You can also pass in an enumerated list of items like strings and have it parse each of them via a seperator character like ‘:’, this can be applied using Seperator=’:’ as can be seen in UserOptions example.
If you pass in a string value instead of a numeric type like for Id input above it will fail validation and display as so:
Nifty, i hear you say. All of this is done with hardly any effort by the developer, all out of the box functionality which as Tony the Tiger would say is juust greeeat!
Finally, there is also another type of attribute setting you can apply if your console app deals with many commands which in turn have many arguments like the ones applied above which is called Verb. Examples of this usage would be FTP programs that have commands like clone, download, upload, etc etc. In our simple example above we will apply a User Admin set of command options for the client to use & with minimal effort by us which will create, amend & delete users.
Below i have created three classes, CreateOptions, AmendOptions & DeleteOptions
These classes each contain the required set of properties for each command operation, for example, CreateOptions will read in all the properties for the user from the cmd line and store these. AmendOptions will read in an Id and the updated Name & Hobbies fields, finally DeleteOptions will read in the Id that is the user to be removed.
Main method has the following API call setup which will listen for what inputs have been supplied and process accordingly, all applied in a nice concise fluent way:
The AddUser, AmendUser & DeleteUser methods would fulfill the processing of the CRUD functionailty, for brevity i have put in place holder text output to illustrate so.
Also notice how i have access to the properties (id, name, hobbies) from each class in each method.
A lot of capability out of the box in a few lines of code, which normally would take a bit of effort if built manually.
I have successfully used this library for building custom command line applications that i plugged into Continuous Integration pipelines using Team City in the past & i have to say its made my life a lot easier as a result.
As usual, all of the code examples above are available on my GITHUB page so feel free to play around. I would recommend having a read over the nuget wiki page provided by their team which was very helpful.
NOW…go forth, & command & conquer your own console applications today!