This project is read-only.

Quick Start

The CommandLineHelper Library automates most of the tasks that a programmer needs to do for each of the console applications that they create. Specifically, it provides the following functionality:
  • It parses the command line and reads the named values into properties in a class that you define.
  • It validates the values passed in based on consitions that you specify.
  • It provides formatted usage help to end-users of your application.

As the developer, all you have to do is create a class with public properties that represent each of the command line values that you would like to receive. You call a method to parse the command line and your class is automatically populated. There are a few attributes that you need to decorate your properties with, but this is all you need to do to in order for the library to know how you would like it to function.

Let's walk through the process of creating a project that takes command line parameters.

Prepare the project
  • From within Visual Studio, create a console application project.
  • Add a reference to the CommandLineHelper.dll file.
Build your class for holding the parameters
  • Create a new class in your project and give it whatever name you like. For the purpose of this document, I will create one called MyParams.
  • Add a public property to your class for each of the values you would like to get from your user on the command line. The name you specify for the property is the name that your user will use on the command line.
Below is an example of a class with one string property and one boolean. The boolean is used as a flag, so if it's specified on the command line then it gets set to true, otherwise it's false.

    class MyParams
    {
        string _path;
        bool _includeSubfolders;

        public bool IncludeSubfolders
        {
            get { return _includeSubfolders; }
            set { _includeSubfolders = value; }
        }

        public string Path
        {
            get { return _path; }
            set { _path = value; }
        }
    }


Decorate the class
  • Next you need to add the "Parameter" attribute to each of the properties that you want to expose on the command line.

    class MyParams
    {
        string _path;
        bool _includeSubfolders;

        [Parameter]
        public bool IncludeSubfolders
        {
            get { return _includeSubfolders; }
            set { _includeSubfolders = value; }
        }

        [Parameter]
        public string Path
        {
            get { return _path; }
            set { _path = value; }
        }
    }


Initiate the parsing operation
  • Create an instance of the parameter class you just added, and then call the static CommandLineHelper.Parse() method. An example is shown below:

        static void Main()
        {
            MyParams myParams = new MyParams();
            if (CommandLineHelper.CommandLineHelper.Parse<MyParams>(ref myParams))
            {
                //command line parsed successfully
                Console.WriteLine("[Path] {0}", myParams.Path);
                Console.WriteLine("[IncludeSubfolders] {0}", myParams.IncludeSubfolders);
            }
        }


Notice that there are no parameters being passed into the main function. The CommandLineParser library reads the command line parameters from the environment for simplicity. The call to Parse() returns true if the command line was parsed successfully. Inside the if block in the sample code, I write the values pulled from the command line.

Run the program with no command line parameters and you should see output that looks something like this:

    [Path]
    [IncludeSubfolders] false


Marking required parameters
  • To make one or more of the command line parameters required, go back to your class that defines the parameters and modify the Property attribute to set the named parameter "Mandatory" to true. In my example, I am only making the Path property a required parameter.

        [Parameter (Mandatory=true)]
        public string Path
        {
            get { return _path; }
            set { _path = value; }
        }


Run the program now without any command line parameters and it will show you a usage error and display usage information.

[Path] Parameter Validation Error - This required parameter must be specified.

NAME
    SimpleConsole

SYNOPSIS
    (no description provided)

SYNTAX
    SimpleConsole [-IncludeSubfolders] -Path <String> [-help] [-detailedhelp]

REMARKS
    For more information, type "SimpleConsole -detailedhelp".

    When specifying names for parameters, the name can be abbreviated as long
    as the abbreviation used is not ambiguous.


To learn how to customize the help screen continue to the Advanced Usage Scenarios topic.




Last edited Oct 5, 2007 at 2:47 AM by Rhy, version 15

Comments

No comments yet.