Previously

In our previous posts we succeeded in creating a command-line tool, supporting arguments and using those arguments to logon to ADAM. Now we will show you how to make your command-line tool intuitive for your users, by adding some well organized help text.

Writing paragraphs

.NET provides us with the Console.WriteLine method to write some text to the command-line. This method does not take into account how wide your command-line window is. So when you write a long sentence to the command-line the sentence will be wrapped, but not in an intelligent way. ADAM provides a method that takes care of wrapping for you. Replace the DisplayGeneralHelp method by this one:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

private static void DisplayGeneralHelp(Arguments args, string[] commands)
{
 ConsoleHelper.WriteParagraph("Some text that is very long and that will" +
  " most probably wrap your text in more then one line. If you would " +
  "write this to the console using Console.Write, it would probably " +
  "wrap some words incorrectly. ADAM takes care of that and makes sure " +
  "that a word is never wrapped.");
 Console.WriteLine();
 ConsoleHelper.WriteParagraph("Some general command-line help.");
 ConsoleHelper.WriteParagraph("Below you can find the available commands:");
 foreach (string command in commands)
 {
  ConsoleHelper.WriteParagraph(command);
 }
 Console.WriteLine();
}

Test by typing the following command and notice how at least the first sentence is split up into multiple lines.

Adam.Blog.CommandLine.exe -?

Writing paragraphs with indentation

In the WhoAmI command, we use some arguments. It is good practice to describe each one of these arguments when we call the help of the WhoAmI command. We will do this by replacing the ShowHelpWhoAmI with the one below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

private static void ShowHelpWhoAmI(string command, Arguments args)
{
 Console.WriteLine();
 ConsoleHelper.WriteParagraph(
  string.Format("The {0} command will display the username, culture and language of the logged on user.", command));
 Console.WriteLine();
 ConsoleHelper.WriteParagraph("These are the arguments:");
 Console.WriteLine();
 int maxLengthOfArguments = _RegistrationArgumentName.Length + 1;
 ConsoleHelper.WriteParagraph("-" + _RegistrationArgumentName.PadRight(maxLengthOfArguments), "Optional. The registration to which you wish to logon.");
 ConsoleHelper.WriteParagraph("-" + _UserNameArgumentName.PadRight(maxLengthOfArguments),
         string.Format(
         "Optional. Used with {0} to indicate which username and password to use when logging on to ADAM.",
         _PasswordArgumentName));
}

When you test this, notice how the argument descriptions are perfectly indented to the length of the argument name. Test it using this command:

Adam.Blog.CommandLine.exe whoami -?

Notice how we use two overloads for the ConsoleHelper.WriteParagraph:

• WriteParagraph(string text): writes the text parameter to the console without any indentation (so left aligned)
• WriteParagraph(string indent, string text): writes the text parameter to the console but indents it with the indent parameter.

What's next

In our final post about command-line tools, we will show you how to display copyright info and ask the user for confirmation before executing a task.