console.waterworks.core

7 Using the Help Attributes

Escape

To help users discover features within your console program, Console.Waterworks.Core (C.W.C.) provides a run-time "help" section. It does this by using the (C#/.Net) attributes you attach to your command-methods. It is, also, optional. So, you do not need to decorate your command-methods if you do not want to. If you have cloned this repository, you can see this in action. To do so, run console program and enter "Help" into the prompt. You should see a list of available commands, a description of what they do and how to use them.

There are four attributes in total. They are:

List Command: Show command at run-time.
Description: Describes what the command does.
Usage: Provides an example of how to use the command.
Parameters: Lists out the commands argument list and their types.

For more information on the "help" attributes, please refer to the following link:

Help Attributes Wiki Page (main Console.Waterworks wiki)

To set-up the "help" section , you must create a command-method first. You can use any name you want. For example, I usually call it help.

Within the "help" command-method, enter the following code:

public static string help()
{
    CW_Liaison liaison = new CW_Liaison();
    // Don't forget your name-space for your ConsoleCommands class
    return liaison.RequestHelpDocumentation("YOUR NAME-SPACE HERE");
}

You will need to add using Console.Waterworks.Core.Attributes to your ConsoleCommands class if you decide to use add this feature.

You must enter the name-space of your ConsoleCommands class into the RequestHelpDocumentation method. Without it, you will get a run-time error.

If you run your console program and type "help", you should find nothing happened. Do not worry, this is usually a sign you have successfully set-up the C.W.C. help section. It, also, means you can start decorating your command-methods with attributes.

When adding attributes to your command-methods, you can add them in any order. Below is an example of what a fully attributed command-method looks like.

[ListCommand()]
[Description("Outputs a message indicating this program is running okay.")]
[Parameters("None")]
[Usage("> Test")]
public static string Test()
{
    // You can add your code here...
    return "Test command working as expected.";
}

A nice side-effect of the attributes is your command-methods are "self-documented". And, because this bit of code is used by the end-user, there is an extra incentive to keep the documentation up-to-date. Who said I'm not an optimist...

For the sake of completeness, I have provided a link to the ConsoleCommands class in CW_Core_Console. Hopefully, seeing more realistic examples will help reduce any confusion. The link is as follows:

ConsoleCommands.cs

Table of Contents