Cinchoo – Command Line Argument Parser, Part 14

Inside Command Line Argument Parser – Automatic Help

Another feature that Cinchoo framework provides you is that, it automatically creates Usage help text.

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

For a sample Command Line object below,

[ChoCommandLineArgObject(ApplicationName = "Hello World", Copyright = "Copyright (c) Cinchoo Inc.")]
public class MyCommandLineArgObject : ChoCommandLineArgObject
{
    [ChoCommandLineArg("D", DefaultValue = "%NOW%", Description = "Business Date.", ShortName = "Today")]
    public DateTime Today
    {
        get;
        set;
    }

    [ChoCommandLineArg("N", DefaultValue = "{100+100}", Description = "No of spaces for a TAB.")]
    public int Count
    {
        get;
        set;
    }

    [ChoCommandLineArg("I", DefaultValue = false, FallbackValue = true, Description = "Include Sub directory.")]
    public bool IncludeSubDir
    {
        get;
        set;
    }

    [ChoCommandLineArg("O", IsRequired = true, Description = "Output Directory.")]
    public string OutFolder
    {
        get;
        set;
    }
}

If the application containing above type executed with the below command line arguments

/help or /? or /h

When creating instance of MyCommandLineArgObject as below,

MyCommandLineArgObject commandLineArgObject = new MyCommandLineArgObject();
Console.WriteLine(commandLineArgObject.ToString());

And run the application, the commandLineArgObject will display the usage as below

Hello World [Version 1.0.0.0]
Copyright (c) Cinchoo Inc.

Cinchoo.Core.CommandLineArgs.Test.exe -D:Today -N:<int> -I:{True|False} -O:[<string>]

Where
        -D      Business Date.
        -N      No of spaces for a TAB.
        -I      Include Sub directory.
        -O      Output Directory.

Cinchoo – Command Line Argument Parser, Part 13

Inside Command Line Argument Parser – Load from file

In some cases, if you have multiple large, complex sets of command-line arguments that you want to run multiple times, Cinchoo framework provides a way to load the command line arguments from a file.

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

Let say you create a file c:\CmdLine.txt with the below command line arguments

N:{100+50} /I -O:C:\Log -D:%NOW%

Sample Command Line object below,

[ChoCommandLineArgObject(ApplicationName = "Hello World", Copyright = "Copyright (c) Cinchoo Inc.")]
public class MyCommandLineArgObject : ChoCommandLineArgObject
{
    [ChoCommandLineArg("D", DefaultValue = "%NOW%", Description = "Business Date.", ShortName = "Today")]
    public DateTime Today
    {
        get;
        set;
    }

    [ChoCommandLineArg("N", DefaultValue = "100", Description = "No of spaces for a TAB.")]
    public int Count
    {
        get;
        set;
    }

    [ChoCommandLineArg("I", DefaultValue = false, FallbackValue = true, Description = "Include Sub directory.")]
    public bool IncludeSubDir
    {
        get;
        set;
    }

    [ChoCommandLineArg("O", IsRequired = true, Description = "Output Directory.")]
    public string OutFolder
    {
        get;
        set;
    }
}

If the application containing above type executed with the below command line arguments (Please note, the file is been passed with @ symbol.)

@"C:\CmdLine.txt"

When creating instance of MyCommandLineArgObject as below,

MyCommandLineArgObject commandLineArgObject = new MyCommandLineArgObject();
Console.WriteLine(commandLineArgObject.ToString());

And run the application, the commandLineArgObject will contain the below values

Hello World [Version 1.0.0.0]
Copyright (c) Cinchoo Inc.

-- Cinchoo.Core.CommandLineArgs.Test.MyCommandLineArgObject Dump --
Today: 1/6/2012 12:32:00 PM
Count: 150
IncludeSubDir: True
OutFolder: C:\Log

Cinchoo – Property Replacer, Part 1

Customizing Property Replacer – Static Properties

If you need that you need to define and use list of your own properties for your requirements, you can do so by adding <key, value> pair to ChoStaticDictionaryPropertyReplacer class. There values are static, will not be evaluated for each time.  Cinchoo framework will take these values for property replacement in various places like Command Line parsing, Configuration Management, Object.ToString() etc.

Example, add CLUSTER_NAME property at the start of the application as below

ChoStaticDictionaryPropertyReplacer.Me.Add("CLUSTER_NAME", "CNYC100123023");

Then, you can use that property by using the below code

string msg = "Cluster Name is %CLUSTER_NAME%";
Console.WriteLine(ChoString.ExpandProperties(msg));

When you run the above statements in an application, the output will be

Cluster Name is CNYC100123023

Cinchoo – Command Line Argument Parser, Part 11

Inside Command Line Argument Parser – Available Properties

In here I’ll list all the available properties in Cinchoo framework.

Properties can be specified with % delimiters as below

%NOW%

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

Cinchoo framework allows you to pass property as command line argument. At run time, the framework replaces with property value.

Global Properties

Below are the list of global properties available for use as command line arguments

• %APPLICATION_NAME% – Application Name.
• %PROCESS_ID% – Process Identifier.
• %THREAD_ID% – Thread Identifier.
• %THREAD_NAME% – Managed .NET Thread Name, if any.
• %RANDOM_NO% – Random integer value.
• %TODAY% – Current Date.
• %NOW% – The current date and time on this computer, expressed as the local time.

Environment Properties

Below are the list of Environment properties available for use as command line arguments

• %CURRENT_DIRECTORY% – The fully qualified path of the current directory; that is, the directory from which this process starts.
• %MACHINE_NAME% – The NetBIOS name of this local computer
• %OS_VERSION% – An OperatingSystem object that contains the current platform identifier and version number.
• %PROCESSOR_COUNT% – The number of processors on the current machine.
• %SYSTEM_DIRECTORY% – The fully qualified path of the system directory.
• %SYSTEM_PAGE_SIZE% – The amount of memory for an operating system’s page file.
• %TICK_COUNT% – The number of milliseconds elapsed since the system started.
• %USER_DOMAIN_NAME% – The network domain name associated with the current user.
• %USER_NAME% – The user name of the person who is currently logged on to the Windows operating system.
• %VERSION% – A Version object that describes the major, minor, build, and revision numbers of the common language runtime.
• %WORKING_SET% – The amount of physical memory mapped to the process context.

Please visit PropertyReplacer section for more information about Property re-placers.

Cinchoo – Command Line Argument Parser, Part 10

Inside Command Line Argument Parser – Parameterized Arguments

Sometimes you may want to pass and assign parameterized dynamic value to command line argument. Cinchoo framework addresses this need.

Let say, you want to pass current date time as command line argument, you can do so as below

N:200 /I -O:C:\Log -D:%NOW%

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

Cinchoo framework looks into the %NOW% command line argument value, replaces and assigns current date time to corresponding member (Today).

[ChoCommandLineArgObject(ApplicationName = "Hello World", Copyright = "Copyright (c) Cinchoo Inc.")]
public class MyCommandLineArgObject : ChoCommandLineArgObject
{
    [ChoCommandLineArg("D", DefaultValue = "%NOW%", Description = "Business Date.", ShortName = "Today")]
    public DateTime Today
    {
        get;
        set;
    }

    [ChoCommandLineArg("N", DefaultValue = 100, Description = "No of spaces for a TAB.")]
    public int Count
    {
        get;
        set;
    }

    [ChoCommandLineArg("I", DefaultValue = false, FallbackValue = true, Description = "Include Sub directory.")]
    public bool IncludeSubDir
    {
        get;
        set;
    }

    [ChoCommandLineArg("O", IsRequired = true, Description = "Output Directory.")]
    public string OutFolder
    {
        get;
        set;
    }
}

If the application containing above type executed with the below command line arguments

N:200 /I -O:C:\Log -D:%NOW%

When creating instance of MyCommandLineArgObject as below,

MyCommandLineArgObject commandLineArgObject = new MyCommandLineArgObject();
Console.WriteLine(commandLineArgObject.ToString());

And run the application, the commandLineArgObject will contain the below values

Hello World [Version 1.0.0.0]
Copyright (c) Cinchoo Inc.

-- Cinchoo.Core.CommandLineArgs.Test.MyCommandLineArgObject Dump --
Today: 1/6/2012 12:32:00 PM
Count: 200
IncludeSubDir: True
OutFolder: C:\Log

In next section, I’ll list you the possible properties available in Cinchoo framework for use…

Cinchoo – Command Line Argument Parser, Part 9

Inside Command Line Argument Parser – Events

In this section, I’ll brief you about list of callback event mechanism available during Command-Line argument parsing, where you can carry out custom actions to meet your needs.

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

Below are the events fired by Cinchoo framework while loading the command line arguments

Object level events

• BeforeCommandLineArgObjectLoaded – Event fired before command line arguments are parsed and loaded.

[ChoBeforeCommandLineArgObjectLoadedHandler]
public void OnBeforeCommandLineArgObjectLoadedHandler(object sender, ChoPreviewCommandLineArgObjectEventArgs args)
{
    args.Cancel = false;
}

• AfterCommandLineArgObjectLoaded – Event fired after command line arguments are parsed and loaded successfully.

[ChoAfterCommandLineArgObjectLoadedHandler]
public void OnAfterCommandLineArgObjectLoadedHandler(object sender, ChoCommandLineArgObjectEventArgs args)
{
}

• CommandLineArgObjectLoadError – Event fired when there was exception found while parsing the command line arguments.

[ChoCommandLineArgObjectLoadErrorHandler]
public void OnCommandLineArgObjectLoadError(object sender, ChoCommandLineArgObjectErrorEventArgs args)
{
    Exception ex = args.Exception;
    args.Handled = true;
}

Member level events

• BeforeCommandLineArgLoaded – Event fired before each command-line argument member loaded.

[ChoBeforeCommandLineArgLoadedHandler]
public void OnBeforeCommandLineArgLoadedHandler(object sender, ChoPreviewCommandLineArgEventArgs args)
{
    if (args.MemberName == "Folders")
    {
        if (args.Value is string)
        {
            string folders = args.Value as string;

            if (!folders.IsNullOrWhiteSpace())
            {
                Folders = folders.SplitNTrim(";");
                args.Cancel = true;
            }
        }
    }
}

• AfterCommandLineArgLoaded – Event fired after each command-line argument member loaded successfully.

[ChoAfterCommandLineArgLoadedHandler]
public void OnAfterCommandLineArgLoadedHandler(object sender, ChoCommandLineArgEventArgs args)
{
    if (args.MemberName == "Folders")
    {
    }
}

• CommandLineArgLoadError – Event fired when there was error while loading command-line argument member.

[ChoCommandLineArgObjectLoadErrorHandler]
public void OnCommandLineArgObjectLoadError(object sender, ChoCommandLineArgObjectErrorEventArgs args)
{
    Exception ex = args.Exception;
    args.Handled = true;
}

• CommandLineArgMemberNotFound – Event fired when there is no command-line member defined for a command-line switch.

[ChoCommandLineArgMemberNotFoundHandler]
public void OnCommandLineArgMemberNotFoundHandler(object sender, ChoCommandLineArgNotFoundEventArgs args)
{
    string cmdLineArgSwitch = args.CmdLineArgSwitch;
    string cmdLineArgValue = args.CmdLineArgValue;
}

• UnrecognizedCommandLineArgFound – Event fired when there is an unrecognized command line switch found.

[ChoUnrecognizedCommandLineArgFoundHandler]
public void OnUnrecognizedCommandLineArgFoundHandler(object sender, ChoUnrecognizedCommandLineArgEventArg args)
{
    string cmdLineArgValue = args.CmdLineArgValue;
}

Cinchoo – Command Line Argument Parser, Part 8

Inside Command Line Argument Parser – Value Converters

Here I’ll show you another way of converting command-line argument value to the underlying member type. Most of the intrinsic types (int, bool, long etc) are converted automatically and stored to corresponding members. For others, there is no straight conversion or Converters available, Cinchoo framework provides a callback mechanism where you have opportunity to convert the value to native member type.

In here, I’ll will show you on how to convert comma separated string value to string array. Define a callback method OnBeforeCommandLineArgLoadedHandler decorated with ChoBeforeCommandLineArgLoadedHandlerAttribute. In there, you can do the conversion in Value member of ChoPreviewCommandLineArgEventArgs and assign to Folders member. Make sure you set false to Cancel to tell the Cinchoo framework to stop processing this member.

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

[ChoCommandLineArgObject(ApplicationName = "Hello World", Copyright = "Copyright (c) Cinchoo Inc.")]
public class MyCommandLineArgObject : ChoCommandLineArgObject
{
    [ChoCommandLineArg("N", DefaultValue = 100, Description = "No of spaces for a TAB.")]
    public int Count
    {
        get;
        set;
    }

    [ChoCommandLineArg("I", DefaultValue = false, FallbackValue = true, Description = "Include Sub directory.")]
    public bool IncludeSubDir
    {
        get;
        set;
    }

    [ChoCommandLineArg("O", IsRequired = true, Description = "Output Directory.")]
    public string OutFolder
    {
        get;
        set;
    }

    [ChoDefaultCommandLineArg(IsRequired = true, Description = "Semi-colon seperated list of folders")]
    public string[] Folders
    {
        get;
        set;
    }

    [ChoBeforeCommandLineArgLoadedHandler]
    public void OnBeforeCommandLineArgLoadedHandler(object sender, ChoPreviewCommandLineArgEventArgs args)
    {
        if (args.MemberName == "Folders")
        {
            if (args.Value is string)
            {
                string folders = args.Value as string;

                if (!folders.IsNullOrWhiteSpace())
                {
                    Folders = folders.SplitNTrim(";");
                    args.Cancel = true;
                }
            }
        }
    }
}

If the application containing above type executed with the below command line arguments

N:200 /I -O:C:\Log "C:\Source1;C:\Source2"

When creating instance of MyCommandLineArgObject as below,

MyCommandLineArgObject commandLineArgObject = new MyCommandLineArgObject();
Console.WriteLine(commandLineArgObject.ToString());

And run the application, the commandLineArgObject will contain the below values

-- Cinchoo.Core.CommandLineArgs.Test.MyCommandLineArgObject Dump --
 Today: 1/3/2012 4:53:00 PM
 Count: 100
 IncludeSubDir: True
 OutFolder: C:\Log
 Folders: C:\Source1; C:\Source2

Cinchoo – Command Line Argument Parser, Part 7

Inside Command Line Argument Parser – Value Converters

Here I’ll talk about the way of converting command-line argument value to the underlying member type. Most of the intrinsic types (int, bool, long etc) are converted automatically and stored to corresponding members. For others, there is no straight conversion available, you can provide Converter for them in order to convert the value to underlying member type.

Cinchoo framework provides some converters out of the box for you to use. You can also create one for your need (Will talk about on creating value converter later).

In here, I’ll will show you on how to convert comma separated string value to string array. The Folders member is decorated ChoTypeConverterAttribute with ChoStringToStringArrayConverter.

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

ChoStringToStringArrayConverter takes string value, split them by ‘;’ separator to string array.

[ChoCommandLineArgObject(ApplicationName = "Hello World", Copyright = "Copyright (c) Cinchoo Inc.")]
public class MyCommandLineArgObject : ChoCommandLineArgObject
{
    [ChoCommandLineArg("N", DefaultValue = 100, Description = "No of spaces for a TAB.")]
    public int Count
    {
        get;
        set;
    }

    [ChoCommandLineArg("I", DefaultValue = false, FallbackValue = true, Description = "Include Sub directory.")]
    public bool IncludeSubDir
    {
        get;
        set;
    }

    [ChoCommandLineArg("O", IsRequired = true, Description = "Output Directory.")]
    public string OutFolder
    {
        get;
        set;
    }

    [ChoDefaultCommandLineArg(IsRequired = true, Description = "Semi-colon seperated list of folders")]
    [ChoTypeConverter(typeof(ChoStringToStringArrayConverter))]
    public string[] Folders
    {
        get;
        set;
    }
}

If the application containing above type executed with the below command line arguments

N:200 /I -O:C:\Log "C:\Source1;C:\Source2"

When creating instance of MyCommandLineArgObject as below,

MyCommandLineArgObject commandLineArgObject = new MyCommandLineArgObject();
Console.WriteLine(commandLineArgObject.ToString());

And run the application, the commandLineArgObject will contain the below values

-- Cinchoo.Core.CommandLineArgs.Test.MyCommandLineArgObject Dump --
 Today: 1/3/2012 4:53:00 PM
 Count: 100
 IncludeSubDir: True
 OutFolder: C:\Log
 Folders: C:\Source1; C:\Source2

Cinchoo – Command Line Argument Parser, Part 6

Inside Command Line Argument Parser – Default Argument

In this section, I’ll talk about defining and using Default command-line arguments member in command line argument object. There may be only one Default command-line argument can be defined in Command-line object.

Default command-line argument is an argument passed without any switch (ex: the argument “C:\Source1;C:\Source2” is the default argument).

N:200 /I -O:C:\Log "C:\Source1;C:\Source2"

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

In a sample Command Line object below,

[ChoCommandLineArgObject]
public class MyCommandLineArgObject : ChoCommandLineArgObject
{
    [ChoCommandLineArg("N", DefaultValue = 100, Description = "No of spaces for a TAB.")]
    public int Count
    {
        get;
        set;
    }

    [ChoCommandLineArg("I", DefaultValue = false, FallbackValue = true, Description = "Include Sub directory.")]
    public bool IncludeSubDir
    {
        get;
        set;
    }

    [ChoCommandLineArg("O", IsRequired = true, Description = "Output Directory.")]
    public string OutFolder
    {
        get;
        set;
    }

    [ChoDefaultCommandLineArg(IsRequired = true, Description = "Semi-colon seperated list of folders")]
    [ChoTypeConverter(typeof(ChoStringToStringArrayConverter))]
    public string[] Folders
    {
        get;
        set;
    }
}

The Folders member is the default command-line argument member. It is decorated with ChoDefaultCommandLineArgAttribute.

If the application containing above type executed with the below command line arguments

N:200 /I -O:C:\Log "C:\Source1;C:\Source2"

When creating instance of MyCommandLineArgObject as below,

MyCommandLineArgObject commandLineArgObject = new MyCommandLineArgObject();
Console.WriteLine(commandLineArgObject.ToString());

And run the application, the commandLineArgObject will contain the below values

-- Cinchoo.Core.CommandLineArgs.Test.MyCommandLineArgObject Dump --
 Today: 1/3/2012 4:53:00 PM
 Count: 100
 IncludeSubDir: True
 OutFolder: C:\Log
 Folders: C:\Source1; C:\Source2

Cinchoo – Command Line Argument Parser, Part 5

Inside Command Line Argument Parser – Required Value

In this section, I’ll explain about defining Required command-line  arguments members in command line argument object. You can specify required flag to any member of Command Line object.

Cinchoo framework will validate and throw an exception if a required command-line argument is missing.

1. Add a reference to Cinchoo.Core.dll

2. Namespace: Cinchoo.Core.Shell

In a sample Command Line object below,

public class MyCommandLineArgObject : ChoCommandLineArgObject
{
    [ChoCommandLineArg("N", DefaultValue = 100, Description ="No of spaces for a TAB.")]
    public int Count
    {
        get;
        set;
    }

    [ChoCommandLineArg("I", DefaultValue = false, FallbackValue=true, Description = "Include Sub directory.")]
    public bool IncludeSubDir
    {
        get;
        set;
    }

    [ChoCommandLineArg("O", IsRequired = true, Description = "Output Directory.")]
    public string OutputDir
    {
        get;
        set;
    }
}

If the application containing above type executed with the below command line arguments

/N:200 /I

Or

N:200 /I -O:

When creating instance of MyCommandLineArgObject, the framework automatically parses the command line arguments, sees there is no value passed for “O” argument and throws an exception with the below message

MyCommandLineArgObject commandLineArgObject = new MyCommandLineArgObject();
Console.WriteLine(commandLineArgObject.ToString());

In this sample, framework throws a ChoCommandLineArgException with the below message

Found exception while loading `O` command line argument.

Missing arg value for 'O' required command line switch.

Cinchoo.Core.CommandLineArgs.Test.exe -N:<int> -I:{True|False} -O:[<string>]

Where
        -D      Business Date.
        -N      No of spaces for a TAB.
        -I      Include Sub directory.
        -O      Output Directory.