ConsoleFx Wiki & Documentation Rss Feed

UPDATED WIKI: Home

jeevanjj — Mon, 19 May 2008 23:53:25 GMT

Documentation | Project Roadmap | Sample Applications

Project Description

ConsoleFx is an attribute-based .NET/Mono framework for easily developing command-line interface (CLI) applications. It automates most of the work involved in creating a CLI application, like command line argument parsing, error handling and validations, all through the use of attributes. With ConsoleFx, you can say goodbye to lengthy cumbersome code to parse your command-line arguments.

Using the ConsoleFx commandline parser, you can declaratively specify a whole host of conditions for specifying command line arguments. These can include the ability to:
* Enforce the order of the command line arguments
* Specify switch options and limit the number of times they can occur as command-line arguments
* Allow parameters to be specified for switch options, and limit the number of parameters that can be specified
* Specify non-switch arguuments and how they are to be used
* Run custom validations on switch parameters and non-switch arguments, including tests for regular expressions, file masks, integers, booleans, enums, etc.
* Automatically map non-switch arguments to strong-typed properties for easier readability
* Perform custom validations that can not be performed by ConsoleFx declaratively

ConsoleFx also provides utility classes for console output capturing and extensions to the Console class. We plan to add other utility classes in the future, making it the all-in-one solution for creating your command-line applications.

Currently, we're finishing up on the first version of ConsoleFx, and planning for the next version has already started.

1.0 Beta 1 Released

ConsoleFx 1.0 Beta 1 has been released. You can download it from ConsoleFx 1.0 Beta 1. This is a feature-complete version of ConsoleFx 1.0. We're working on completing the sample applications and documentation.
If too many bugs are reported for this release, we may decide to go in for a 2nd beta, before proceeding to the final release.
Please report bugs, feature requests and other issues at the Issue Tracker tab. Make sure you file issues under the correct release.

SourceForge Information

The ConsoleFx project originated at SourceForge.net. We will continue to use the SourceForge source control repository until CodePlex has working Subversion support.
Until then, you can use these SourceForge links:

ConsoleFx home on SF.net | Subversion URL | Discussion Forum

UPDATED WIKI: Home

jeevanjj — Fri, 03 Aug 2007 09:14:35 GMT

Documentation | Project Roadmap | Sample Applications

Project Description

1.0 Beta 1 Released

SourceForge Information

UPDATED WIKI: Doc_GS_SettingUp

jeevanjj — Wed, 18 Jul 2007 12:56:08 GMT

To get started. create a new Console Application project and add a reference to the ConsoleFx.dll assembly.

The typical code in a ConsoleFx application will be:

The command-line handling code, where you will create methods and properties decorated with the ConsoleFx attributes. These will be used to specify switches and parameters, perform validations, handle exceptions, etc.
The main logic of your application.

To improve readability, we recomment a convention of splitting the main program class into two files using the partial class feature in C# 2.0.
According to this convention, we split the main class into two

Import the ConsoleFx namespace into your start-up class and code it as follows:

[CommandLine]
public class Program
{
    public static int Main(string[] args)
    {
        return CommandLine.Run<Program();
    }
}

CommandLine Attribute

The CommandLine attribute specifies that the Program class will contain the ConsoleFx code for this application. It is mandatory to specify this attribute.
CommandLineAttribute accepts two optional parameters:

Grouping: An enum of type CommandLineGrouping. It specifies whether ConsoleFx should enforce the ordering of switches and parameters.

    public enum CommandLineGrouping
    {
        DoesNotMatter,
        SwitchesBeforeArguments,
        SwitchesAfterArguments
    }

DoesNotMatter: This is the default value and specifies that switches and parameters can be specified in any order.
SwitchesBeforeArguments: All the switches should be specified before the parameters.
SwitchesAfterArguments: All the parameters should be specifed before the switches.

DisplayUsageOnError: This is a bool parameter that specifies whether the application's usage details will be specified when any unhandled errors is encountered. See the Handling Errors section to understand how to provide error handlers for ConsoleFx.

If set to true, the usage is displayed after the error message, otherwise only the error message is shown. The default us true.

For the GenerateHash application, we'll use the defaults for the CommandLine attribute.

Calling ConsoleFx

We need to make one call from the program's Main() method, which will pass the command-line arguments to ConsoleFx and initiate it's processing. This is done using the static CommandLine.Run() method.

CommandLine.Run<Program>(args);

Run() is a generic method. The type parameter should be the class that contains the ConsoleFx code (the class with the CommandLine attribute).

UPDATED WIKI: Documentation

jeevanjj — Wed, 18 Jul 2007 12:39:40 GMT

Getting started with ConsoleFx

Best Practices

Using partial classes
Using the ConsoleProgram class

Utility classes

ConsoleEx
ConsoleCapture

Miscallaneous Topics

Creating custom validators
Using ConsoleFx in GUI applications
Using ILMerge to create single EXE's

UPDATED WIKI: Doc_GS_SettingUp

jeevanjj — Wed, 18 Jul 2007 10:40:10 GMT

To get started. create a new Console Application project and add a reference to the ConsoleFx.dll assembly.

Import the ConsoleFx namespace into your start-up class and code it as follows:

[CommandLine]
public class Program
{
    public static int Main(string[] args)
    {
        return CommandLine.Run<Program();
    }
}

CommandLine Attribute

Grouping: An enum of type CommandLineGrouping. It specifies whether ConsoleFx should enforce the ordering of switches and parameters.

    public enum CommandLineGrouping
    {
        DoesNotMatter,
        SwitchesBeforeArguments,
        SwitchesAfterArguments
    }

DoesNotMatter: This is the default value and specifies that switches and parameters can be specified in any order.
SwitchesBeforeArguments: All the switches should be specified before the parameters.
SwitchesAfterArguments: All the parameters should be specifed before the switches.

DisplayUsageOnError: This is a bool parameter that specifies whether the application's usage details will be specified when any unhandled errors is encountered. See the Handling Errors section to understand how to provide error handlers for ConsoleFx.

Calling ConsoleFx

UPDATED WIKI: Doc_GS

jeevanjj — Wed, 18 Jul 2007 10:38:46 GMT

This section will take you through the steps to create a ConsoleFx command-line application from scratch. The application being created here is the CleanDirectory application that ships with

CleanDirectory is a command-line application that can be used to delete select files and directories from a specified directory tree. A common use for this application is for .NET developers to clean their project directories (remove bin and obj directories, *.user files, etc) before packaging the source code.

The command-line usage of the CleanDirectory app is:

CLEAN [-dir:<directory mask>] [-file:<file mask>] [-norecurse] <base directory>

-dir specifies the directory mask/name that you want to delete. If such a directory is encountered anywhere in the specified directory tree, it will be removed, along with it's sub-directories.
-file specifies the file mask/name that you want to delete from anywhere in the specified directory tree.
-norecurse specifies that the application should not clean any sub-directories under the specified base directory.

<base directory> is the directory where the cleaning should be performed.
The -dir and -file options can be specified any number of times.

In addition, you can get help on the usage by typing:

CLEAN -? or CLEAN -help or simply CLEAN

Here's a sample usage of the application to clean a VS.NET project folder:

CLEAN -dir:bin -dir:obj -file:*.user C:\MyProject

Don't focus too much on the actual code that does the cleaning. What we're interested in here is the way the program uses ConsoleFx attributes to specify command-line switches and parameters, validate them, handle exceptions, etc.

Before we start, here are a few terms that ConsoleFx uses to identify the command-line arguments:

Switch: This is a command-line option, prefixed with a hyphen (-) or a forward slash (/).
Switch Parameters: These are optional parameters that be attached to a switch. They use the format <switch>:param1,param2,param3,...,paramN
Parameter: Any non-switch command-line argument.

Table of Contents | Next: Setting up

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 16:19:40 GMT

Version 1.0 Final new features
Version 2.0 features
Version not yet decided

Version 1.0 Final new features

Additional validators

New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item: Additional validators

Improve command-line error handling

Update the exception messages in all exception classes provided by ConsoleFx. The developer should be able to use these messages directly for any command-line errors.

Related issue tracker item: Update exception error messages

Simplify common usage scenarios

Provide base classes for handling common scenarios, such as when there is only a single program mode, or when there is a single normal program mode along with help.

Create overloads for any attribute constructors that accept a program mode parameter. For single program mode apps, this can default to ProgramMode.Normal.
Provide a base class called SingleModeProgram that contains common virtual functions, that can simply be overloaded as needed.
Remove the common ConsoleProgram class, if needed

For example:

public sealed class MyProgram : SingleModeProgram
{
    public override int Execute(string[] parameters)
    {
        ...
    }
 
    public override void DisplayUsage()
    {
        ...
    }
 
    public override int GetMode(string[] parameters)
    {
        ...
    }
}

Version 2.0 features

Automate usage display

ConsoleFx will be able to automatically generate the usage display data from the metadata in the code. The developer will not need to manually print out the usage display by writing many Console.WriteLine() statements.

Usage display plug-ins

Instead of fixing the way in which the usage display is generated, we will provide this as a simple plug-in mechanism, with ConsoleFx providing a default plug-in class out-of-the-box.
Developers can write their own plug-ins for changing the way the application displays it's usage.
Note: Depending on time, we might release additional usage display plug-ins out-of-the-box.

Console window handling attribute

New attribute(s) that will control the behavior of the console window, such as how to handle Ctrl+C key presses. Also allows to specify parameters to initialize the console window, such as setting it's height and width.

Version not yet decided

Multi-language support

Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end

Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support

Ability to override default command-line argument values from a configuration file.

ASCII art support

Support for generating ASCII art from strings and from image files.

Create and publish XML doc comments

UPDATED WIKI: Home

jeevanjj — Fri, 13 Jul 2007 16:15:03 GMT

Documentation | Project Roadmap | Sample Applications

Project Description

1.0 Beta 1 Released

SourceForge Information

UPDATED WIKI: Home

jeevanjj — Fri, 13 Jul 2007 16:10:06 GMT

Documentation | Project Roadmap

Project Description

1.0 Beta 1 Released

SourceForge Information

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 15:38:29 GMT

Version 1.0 Final new features
Version 2.0 features
Version not yet decided

Version 1.0 Final new features

Additional validators

New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item: Additional validators

Improve command-line error handling

Simplify common usage scenarios

Provide base classes for handling common scenarios, such as when there is only a single program mode, or when there is a single normal program mode along with help.

Create overloads for any attribute constructors that accept a program mode parameter. For single program mode apps, this can default to ProgramMode.Normal.
Provide a base class called SingleModeProgram that contains common virtual functions, that can simply be overloaded as needed.
Remove the common ConsoleProgram class, if needed

For example:

public sealed class MyProgram : SingleModeProgram
{
    public override int Execute(string[] parameters)
    {
        ...
    }
 
    public override void DisplayUsage()
    {
        ...
    }
 
    public override int GetMode(string[] parameters)
    {
        ...
    }
}

Version 2.0 features

Automate usage display

Usage display plug-ins

Console window handling attribute

Version not yet decided

Multi-language support

Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end

Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support

Ability to override default command-line argument values from a configuration file.

ASCII art support

Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 15:08:37 GMT

Version 1.0 Final new features
Version 2.0 features
Version not yet decided

Version 1.0 Final

Additional validators

New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item: Additional validators

Improve command-line error handling

Simplify common usage scenarios

Provide base classes for handling common scenarios, such as when there is only a single program mode, or when there is a single normal program mode and along with help.

Create overloads for any attribute constructors that accept a program mode parameter. For single program mode apps, this can default to ProgramMode.Normal.
Provide a base class called SingleModeProgram that contains common virtual functions, that can simply be overloaded as needed.
Remove the common ConsoleProgram class, if needed

For example:

public sealed class MyProgram : SingleModeProgram
{
    public override int Execute(string[] parameters)
    {
        ...
    }
 
    public override void DisplayUsage()
    {
        ...
    }
 
    public override int GetMode(string[] parameters)
    {
        ...
    }
}

Version 2.0 Features

Automate usage display

Usage display plug-ins

Console window handling attribute

Version not yet decided

Multi-language support

Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end

Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support

Ability to override default command-line argument values from a configuration file.

ASCII art support

Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 14:44:35 GMT

Version 1.0 Final new features
Version 2.0 features
Version not yet decided

Version 1.0 Final

Additional validators

New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item: Additional validators

Improve command-line error handling

Simplify common usage scenarios

Provide base classes for handling common scenarios, such as when there is only a single program mode, or when there is a single normal program mode and along with help.

Single program mode

Create overloads for any attribute constructors that accept a program mode parameter. For single program mode apps, this can default to ProgramMode.Normal.
Provide a base class called SingleModeProgram that contains common virtual functions, that can simply be overloaded as needed.

Apply similar features for a single normal program mode with help.

Version 2.0 Features

Automate usage display

Usage display plug-ins

Console window handling attribute

Version not yet decided

Multi-language support

Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end

Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support

Ability to override default command-line argument values from a configuration file.

ASCII art support

Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 14:34:05 GMT

Version 1.0 Final new features
Version 2.0 features
Version not yet decided

Version 1.0 Final

Additional validators

New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item: Additional validators

Improve command-line error handling

Simplify common usage scenarios

Provide a much simpler mechanism in common usages, such as when there is only one program mode, or a normal program mode and a help program mode.

Version 2.0 Features

Automate usage display

Usage display plug-ins

Console window handling attribute

Version not yet decided

Multi-language support

Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end

Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support

Ability to override default command-line argument values from a configuration file.

ASCII art support

Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 14:33:04 GMT

Version 1.0 Final new features
Version 2.0 features
Version not yet decided

Version 1.0 Final

Additional validators

New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item: Additional validators

Improve command-line error handling

Simplify common usage scenarios

Provide a much simpler mechanism in common usages, such as when there is only one program mode, or a normal program mode and a help program mode.

!!Version 2.0 Features

Automate usage display

Usage display plug-ins

Console window handling attribute

Version not yet decided

Multi-language support

Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end

Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support

Ability to override default command-line argument values from a configuration file.

ASCII art support

Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 12:53:59 GMT

Version 1.0 Final new features
Version 2.0 features
Version not yet decided

Version 1.0 Final

Additional validators

New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item: Additional validators

Improve command-line error handling

Provide more information on command-line exceptions, and make the default error messages more user-friendly.

Simplify common usage scenarios
Provide a much simpler mechanism in common usages, such as when there is only one program mode, or a normal program mode and a help program mode.

!!Version 2.0 Features

Automate usage display
ConsoleFx will be able to automatically generate the usage display data from the metadata in the code. The developer will not need to manually print out the usage display by writing many Console.WriteLine() statements.

Usage display plug-ins
Instead of fixing the way in which the usage display is generated, we will provide this as a simple plug-in mechanism, with ConsoleFx providing a default plug-in class out-of-the-box.
Developers can write their own plug-ins for changing the way the application displays it's usage.
Note: Depending on time, we might release additional usage display plug-ins out-of-the-box.

Console window handling attribute
New attribute(s) that will control the behavior of the console window, such as how to handle Ctrl+C key presses. Also allows to specify parameters to initialize the console window, such as setting it's height and width.

Version not yet decided

Multi-language support
Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end
Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support
Ability to override default command-line argument values from a configuration file.

ASCII art support
Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 12:49:16 GMT

Version 1.0 Final

Blah

Additional validators
New custom validator attributes for the following:

Floating-point numbers
File masks
Urls
E-mail addresses

Related issue tracker item:

Improve command-line error handling
Provide more information on command-line exceptions, and make the default error messages more user-friendly.

Simplify common usage scenarios
Provide a much simpler mechanism in common usages, such as when there is only one program mode, or a normal program mode and a help program mode.

!!Version 2.0 Features

Automate usage display
ConsoleFx will be able to automatically generate the usage display data from the metadata in the code. The developer will not need to manually print out the usage display by writing many Console.WriteLine() statements.

Usage display plug-ins
Instead of fixing the way in which the usage display is generated, we will provide this as a simple plug-in mechanism, with ConsoleFx providing a default plug-in class out-of-the-box.
Developers can write their own plug-ins for changing the way the application displays it's usage.
Note: Depending on time, we might release additional usage display plug-ins out-of-the-box.

Console window handling attribute
New attribute(s) that will control the behavior of the console window, such as how to handle Ctrl+C key presses. Also allows to specify parameters to initialize the console window, such as setting it's height and width.

Version not yet decided

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 12:41:58 GMT

Version 1.0 Final

Additional validators
New validators for floating numbers, e-mail addresses, web page url's, file masks, etc.

Improve command-line error handling
Provide more information on command-line exceptions, and make the default error messages more user-friendly.

Simplify common usage scenarios
Provide a much simpler mechanism in common usages, such as when there is only one program mode, or a normal program mode and a help program mode.

Version not yet decided

Automate usage display
ConsoleFx will be able to automatically generate the usage display data from the metadata in the code. The developer will not need to manually print out the usage display by writing many Console.WriteLine() statements.

Usage display plug-ins
Instead of fixing the way in which the usage display is generated, we will provide this as a simple plug-in mechanism, with ConsoleFx providing a default plug-in class out-of-the-box.
Developers can write their own plug-ins for changing the way the application displays it's usage.
Note: Depending on time, we might release additional usage display plug-ins out-of-the-box.

Multi-language support
Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end
Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support
Ability to override default command-line argument values from a configuration file.

Console window handling attribute
New attribute(s) that will control the behavior of the console window, such as how to handle Ctrl+C key presses. Also allows to specify parameters to initialize the console window, such as setting it's height and width.

ASCII art support
Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 12:39:59 GMT

ConsoleFx 1.0 is currently in beta, and it's feature-set has been frozen for this release. We have started planning the feature-set for 2.0 and later versions. Here are some of the items we have in mind. If you'd like a feature to be included, please add a feature request to the Issue Tracker and categorize it as a feature request for ConsoleFx 2.0.

Version 1.0 Final new features
Version not yet decided

!! Version 1.0 Final

Additional validators
New validators for floating numbers, e-mail addresses, web page url's, file masks, etc.

Improve command-line error handling
Provide more information on command-line exceptions, and make the default error messages more user-friendly.

Simplify common usage scenarios
Provide a much simpler mechanism in common usages, such as when there is only one program mode, or a normal program mode and a help program mode.

!! Version not yet decided

Automate usage display
ConsoleFx will be able to automatically generate the usage display data from the metadata in the code. The developer will not need to manually print out the usage display by writing many Console.WriteLine() statements.

Usage display plug-ins
Instead of fixing the way in which the usage display is generated, we will provide this as a simple plug-in mechanism, with ConsoleFx providing a default plug-in class out-of-the-box.
Developers can write their own plug-ins for changing the way the application displays it's usage.
Note: Depending on time, we might release additional usage display plug-ins out-of-the-box.

Multi-language support
Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end
Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support
Ability to override default command-line argument values from a configuration file.

Console window handling attribute
New attribute(s) that will control the behavior of the console window, such as how to handle Ctrl+C key presses. Also allows to specify parameters to initialize the console window, such as setting it's height and width.

ASCII art support
Support for generating ASCII art from strings and from image files.

UPDATED WIKI: Roadmap

jeevanjj — Fri, 13 Jul 2007 12:26:30 GMT

ConsoleFx 1.0 is currently in beta, and it's feature-set has been frozen for this release. We have started planning the feature-set for 2.0 and later versions. Here are some of the items we have in mind. If you'd like a feature to be included, please add a feature request to the Issue Tracker and categorize it as a feature request for ConsoleFx 2.0.

Version 1.0 Final new features
Version not yet decided

anchor:version1!! Version 1.0 Final

Additional validators
New validators for floating numbers, e-mail addresses, web page url's, file masks, etc.

Improve command-line error handling
Provide more information on command-line exceptions, and make the default error messages more user-friendly.

Simplify common usage scenarios
Provide a much simpler mechanism in common usages, such as when there is only one program mode, or a normal program mode and a help program mode.

anchor:unversioned!! Version not yet decided

Automate usage display
ConsoleFx will be able to automatically generate the usage display data from the metadata in the code. The developer will not need to manually print out the usage display by writing many Console.WriteLine() statements.

Usage display plug-ins
Instead of fixing the way in which the usage display is generated, we will provide this as a simple plug-in mechanism, with ConsoleFx providing a default plug-in class out-of-the-box.
Developers can write their own plug-ins for changing the way the application displays it's usage.
Note: Depending on time, we might release additional usage display plug-ins out-of-the-box.

Multi-language support
Multi-language support for the usage display, switch names, etc.

ConsoleFx GUI front-end
Windows GUI application that will accept a command-line EXE application written in ConsoleFx, and dynamically generate a Windows UI for entering the command-line arguments.

Configuration file support
Ability to override default command-line argument values from a configuration file.

Console window handling attribute
New attribute(s) that will control the behavior of the console window, such as how to handle Ctrl+C key presses. Also allows to specify parameters to initialize the console window, such as setting it's height and width.

ASCII art support
Support for generating ASCII art from strings and from image files.