Listing 9.2 Test1.exe with value contains double quotes

>Test1.exe /name:"Raj""s msg" /msg:"Hello world" /r:True

9.3 Loading arguments from external file

A program may have multiple large, complex sets of command line arguments and wanted to run them multiple times, in this case you can save the values to external file and pass the file to the program. It saves time and effort of retyping the command line argument values for each run.

>Test1.exe @"C:\Sample\CmdLineArgs.txt"

10. Validation

In this section, I'll talk about how to validate each command line argument member values, different approaches of validation methods, etc. Any application that accepts input from command line arguments must ensure that the information is valid in terms of some set of rules that you specify. For example, you may need to check that a customer's phone number has the correct number of digits, or that a date falls within a particular range. In addition, if the validation fails, you may need to send an error message that explains what is wrong. 

Cinchoo provides library of classes, called validators, that supplies the code for validating command line argument members. For example, one validator checks for null strings and another validator checks that a string contains only specific set of characters etc. In some cases, you may want to define your own custom validator and use them to validate the member values.

There are special validaters used to compose, aggregate other validators and group them together in a rule set.

• ChoAndCompositeValidator - It groups other validators, all validators in this composite validator must be true for a successful validation.
• ChoOrCompositeValidator - It groups other validators, at least one validators in the composite validator must be true for a successful validation.

If you want to avoid validations using this library feature and take control of validation, you can do so in couple of ways

• Callback mechanism - OnAfterCommandLineArgLoaded override method can be used to put custom logic to validate the command line argument value.
• Property Setter mechanism - This is another place where you can do custom validation on these member values.

10.1 Using Validators

The following procedures explains how to use validators in your command line argument object members. There are two ways to use validators for your command line argument members

• ChoValidatorAttribute - An generic validator attribute, used in case specific validator does not have corresponding attribute. 
• Validator specific attribute - These are customized validator attributes for each validator. For example, ChoStringValidatorAttribute is the attribute for ChoStringValidator class.  

Cinchoo supports the following validators out of the box

• ChoValidators - Validators that Cinchoo library provides itself. You may find number of them under Cinchoo.Core namespace. For example, ChoNotNullValidator, ChoNotNullOrEmptyValidator etc.
• BCL Configuration Validators - Validators that .NET BCL library provides. You can find them System.Configuration namespace. For example, StringValidator, IntegerValidator etc.
• BCL DataAnnotation Validators - Another set of validators that .NET BCL library provides under System.ComponentModel.DataAnnotations namespace.

10.1.1 Using ChoValidatorAttribute

This is one way of specifying validation rules to command line argument members. In case where there is no validator attribute available for a specific validator, this attribute is here to rescue. This attribute takes validator type as input. The validator type can be one of below derived classes

• Cinchoo.Core.ChoValidator - There are number of validators that Cinchoo framework library offers to use in your application.
• System.Configuration.ConfigurationValidatorBase (System.Configuration.dll) - These set of validators .NET BCL offers to use.

Below are the available optional properties for this attribute

• ConstructorArgs - Optional. Most of the validators accepts some mandorary parameters through constructor to perform the validation on command line object members. These parameters can be specified through this property. It takes object[] as value. These values are positional constructor arguments.
• ConstructorArgsText - Optional string value. The constructor arguments can be specified as text and each value is seperated by ';'.
• KeyValuePropertiesText - Optional string value. It is a key value pair seperated by ';' character to set validator property values. For example, "MinValue=1;MaxValue=10".

Listing 10.1 CommandLine Argument Object with validators

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get;
        set;
    }
}

In the sample above, the member 'XmlFilePath' is specified with 2 validations. It must be not null and must contain minimum 10 characters. The sample shows how you can use ChoValidatorAttribute to define the validators those dont have corresponding custom validator attributes. Note, multiple validators specified at the top level are combined and validated as AND condition by default. Validation orders are NOT guaranteed sequencial. 

'OutputDirectory' member is decorated with custom validator attributes correponding to validators. In here, it is decorated with ChoStringValidatorAttribute and ChoContainsCharatersValidatorAttribute. It gives flexibilty, simplicity and type safety in declaring validators.

Create a console application and create an object of ChoAppCmdLineParams as below

Listing 10.2 Main method

class Program
{
    static void Main(string[] args)
    {
        ChoAppCmdLineParams cmdLineParams = new ChoAppCmdLineParams();
        Console.WriteLine(cmdLineParams.ToString());
    }
}

Listed below are test runs of the program with different arguments

Listing 10.3 Test1.exe with no arguments

>Test1.exe
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `xmlfile` command line argument.

The string must be at least 10 characters long.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

In the above run, the executable was run without passing any command line arguments. The application is trying to instantiate the ChoAppCmdLineParams object. While creating such object, the framework tries to validate the member values. In this case, the positional command line argument 'xmlFilePath' is failed to validate. The application termintes with exception.

Listing 10.4 Test1.exe with incorrect output directory value

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"C:\Windows\Systems\Xcpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `o` command line argument.

The value must contains ALL of the 'A' characters.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

In the above test run, the executable was run with arguments. The positional argument 'XmlFilePath' passed the validation (not null AND contains more than 10 characters). But it failed at validating 'OutputDirectory'. It does not contain character 'A' in it. The application terminates with exception.

Listing 10.5 Test1.exe with correct values

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"C:\Windows\Systems\Acpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

-- ConsoleApplication2.ChoAppCmdLineParams1 State --
        XmlFilePath: C:\Windows\Systems\cpanal.xml
        OutputDirectory: C:\Windows\Systems\Acpanal.xml

Press any key to continue . . .

In the above test run, the executable was run with valid arguments. The positional argument 'XmlFilePath' as well as 'OutputDirectory' passed the validation without any errors.

10.1.2 Using Custom Validator Attributes

Previous section I've talked about using generic validator attribute in defining validations on command line argument members. It paves the way to use the validators without validator attributes. Some validators comes with custom validator attributes. It is simple and straight forward to use and type safe. In the sample below, OutoutDirectory member defines 2 validators with its custom attributes. 

Listing 10.6 CommandLine Argument Object with validators

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get;
        set;
    }
}

10.2 Callback Mechanism

In cases you want to perform some complex validation on members, you can do so with this mechanism. Simply override OnAfterCommandLineArgLoaded method in your command line class as below 

Listing 10.6 CommandLine argument object with custom validation

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams1 : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get;
        set;
    }

    protected override void OnAfterCommandLineArgLoaded(string memberName, object value)
    {
        if (memberName == "OutputDirectory")
        {
            if (!((string)value).StartsWith(@"C:\"))
                throw new ArgumentException("Invalid directory passed.");
        }
        else
            base.OnAfterCommandLineArgLoaded(memberName, value);
    }
}

In the above sample code shows how to validate members using callback mechanism. If the 'OutputDirectory' member value does not starts with 'C:\', throws an exception. 

Listing 10.7 Test1.exe with incorrect output directory value

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"D:\Windows\Systems\Xcpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `o` command line argument.

Invalid directory passed.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

If you run the sample with the above argument values, validation failes for 'OutputDirectory' member with exception 'Invalid directory passed.'.

10.3 Property Setter Mechanism

This is one another way to perform complex validation on members. It is exact similar approach as Callback Machanism. In here the validation can be carried out at the property setter for property command line members. See below sample

Listing 10.8 CommandLine argument object with custom validation

[ChoCommandLineArgObject(Description = "Utility to generate schema or class files from given source.")]
public sealed class ChoAppCmdLineParams1 : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "xmlfile", IsRequired = true, Description = "Name of an xml file to infer xsd schema from.")]
    [ChoValidator(typeof(ChoNotNullOrWhiteSpaceValidator))]
    [ChoValidator(typeof(StringValidator), ConstructorArgsText = "10")]
    public string XmlFilePath
    {
        get;
        set;
    }

    private string _outputDirectory;

    [ChoCommandLineArg("o", Description = "The output directory to create files in. The default is the current directory.")]
    [ChoStringValidator(MinLength = 10)]
    [ChoContainsCharactersValidator("A")]
    public string OutputDirectory
    {
        get { return _outputDirectory; }
        set
        {
            if (!value.StartsWith(@"C:\"))
                throw new ArgumentException("Invalid directory passed.");

            _outputDirectory = value;
        }
    }
}

In the above sample code shows how to validate members using property setter mechanism. The 'OutputDirectory' property validation is handled in property setter. If the value does not starts with 'C:\', throws an exception. 

Listing 10.9 Test1.exe with incorrect output directory value

>Test1.exe "C:\Windows\Systems\cpanal.xml" /o:"D:\Windows\Systems\Xcpanal.xml"
ConsoleApplication2 [Version 1.0.0.0]
Copyright c  2014

Utility to generate schema or class files from given source.

Found exception while loading `o` command line argument.

Invalid directory passed.

ConsoleApplication2.exe xmlfile [/o:<string>]

        xmlfile Name of an xml file to infer xsd schema from.
        /o      The output directory to create files in. The default is the
                current directory.

Press any key to continue . . .

If you run the sample with the above argument values, validation failes for 'OutputDirectory' member with exception 'Invalid directory passed.'.

11. Command Line Object Builder (Grouping)

So far we have learned about defining and consuming individual command line argument object in applications. It best suited for applications with single functionality with the arguments. Some applications performs multiple functions with their own arguments. For example, you have an application which processes data for various input data (network, file, internet etc.) which requires their own respective arguments. It means about having some sort of factory which you can define these contexts with. Basically the first argument would define the context to look up (network, file, internet etc.) then any following arguments would just act as that specific context's arguments.

'NET' dos command is the perfect example of this scenario. If you type 'net' produce this

c:\>net
The syntax of this command is:

NET
    [ ACCOUNTS | COMPUTER | CONFIG | CONTINUE | FILE | GROUP | HELP |
      HELPMSG | LOCALGROUP | PAUSE | SESSION | SHARE | START |
      STATISTICS | STOP | TIME | USE | USER | VIEW ]

c:\>net ACCOUNTS /?
The syntax of this command is:

NET ACCOUNTS
[/FORCELOGOFF:{minutes | NO}] [/MINPWLEN:length]
              [/MAXPWAGE:{days | UNLIMITED}] [/MINPWAGE:days]
              [/UNIQUEPW:number] [/DOMAIN]

11.1 Defining Command Line Argument Builder

First define command line object builder as below

Listing 11.1 Command line argument builder object

[ChoCommandLineArgBuilder]
public class NetCmdBuilder : ChoCommandLineArgBuilder
{
    [ChoCommandLineArgBuilderCommand("START", typeof(STARTCmdLineArgObject), Order = 0)]
    [ChoCommandLineArgBuilderCommand("STOP", typeof(STOPCmdLineArgObject), Order = 1)]
    [ChoCommandLineArgBuilderCommand("COMPUTER", typeof(COMPUTERCmdLineArgObject), Order = -1)]
    public NetCmdBuilder()
    {
    }
}

The code above illustrates about defining command line object builder object. First thing define a builder class (ex. NetCmdBuilder) from ChoCommandLineArgBuilder class, it indicates that this object is a command line argument builder object. And it must be decorated with ChoCommandLineArgBuilderAttribute to complete the definition. Besides that, we need to start defining commands mapping using ChoCommandLineArgBuilderCommandAttribute in the default constructor of the builder. In the above example, the builder defined with 3 commands START, STOP and COMPUTER mapped with STARTCmdLineArgObject, STOPCmdLineArgObject and COMPUTERCmdLineArgObject respectively. The order in the attribute describes about the display order of the commands in the usage text.

Listing 11.2 COMPUTERCmdLineArgObject

public enum Action { ADD, DEL };

[ChoCommandLineArgObject(DoNotShowUsageDetail = true)]
public class COMPUTERCmdLineArgObject : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "\\\\computername", IsRequired = true, Order = 0)]
    public string ComputerName;

    [ChoCommandLineArg("action", IsRequired = true)]
    public Action Action;
}

The above command line argument contains two members, ComputerName - positional required argument and Action - an required enum argument. Note, DoNotShowUsageDetail is true tells the framework not to show the details of each member argument in the usage text.

Listing 11.3 STARTCmdLineArgObject

[ChoCommandLineArgObject]
public class STARTCmdLineArgObject : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "service")]
    public string ServiceName;
}

Listing 11.4 STOPCmdLineArgObject

[ChoCommandLineArgObject(DoNotShowUsageDetail = true)]
public class STOPCmdLineArgObject : ChoCommandLineArgObject
{
    [ChoPositionalCommandLineArg(1, "service", IsRequired = true)]
    public string ServiceName;
}

Listing 11.5 Main Method

class Program
{
    static void Main(string[] args)
    {
        NetCmdBuilder netCmdBuilder = new NetCmdBuilder();
        Console.WriteLine(netCmdBuilder.CommandLineArgObject.ToString());
    }
}

Lets start by creating new instance of netCmdBuilder object. Thats all. The framework does the major lifting of the work behind the scene. After successful load of the arguments, CommandLineArgObject member of the builder object is loaded with matched command object based on the context passed to the executable as argument.

Listed below are test runs of the programs with different set of arguments and its output.

Listing 11.6 net.exe with no arguments

c:\>net

The syntax of this command is:

NET [COMPUTER | START | STOP]

Press any key to continue . . .

c:\>net COMPUTER

Missing '\\computername' argument.

NET COMPUTER \\computername {/ADD | /DEL}
Press any key to continue . . .<span id="cke_bm_151E" style="display: none;"> </span>

c:\>net COMPUTER \\NYC123453 /DEL

-- CommadLineObjectBuilderSample.COMPUTERCmdLineArgObject State --
        ComputerName: \\NYC123453
        Action: DEL

Press any key to continue . . .

[ChoCommandLineArgBuilder]
public class NetCmdBuilder : ChoCommandLineArgBuilder
{
    [ChoCommandLineArgBuilderCommand("START", typeof(STARTCmdLineArgObject), Order = 0)]
    [ChoCommandLineArgBuilderCommand("STOP", typeof(STOPCmdLineArgObject), Order = 1)]
    [ChoCommandLineArgBuilderCommand("COMPUTER", typeof(COMPUTERCmdLineArgObject), Order = -1)]
    public NetCmdBuilder()
    {
    }
}

[ChoCommandLineArgBuilder]
public class ChoNETCommandLineArgBuilder : ChoCommandLineArgBuilder
{
    [ChoCommandLineArgBuilderCommand("ACCOUNTS", typeof(ChoAppCmdLineParams))]
    public ChoNETCommandLineArgBuilder()
    {
    }

    public override Type GetCommandLineArgObjectType(string command)
    {
        if (command == "COMPUTER")
            return typeof(COMPUTERCmdLineArgObject);
        else
            return base.GetCommandLineArgObjectType(command);
    }
}