Auto-generated usage help

Previous: Defining the application arguments | Table of contents

At this point in the walk-through, if you were to run the application with the "/?" argument, you would get something like this:

UsageOutput.png

As you can see, ConsoleFx tries to build some kind of help content, but it is woefully inadequate and in some cases the information is incorrect.

ConsoleFx uses an extensible system of classes called usage builders to construct the usage help content. By default, ConsoleFx uses an internal usage builder that tries to construct the help content automatically. However, for this to work, we need to provide additional information in the code, or we end up with output similar to what is shown above.

Note: ConsoleFx also provides an additional usage builder called the Resource usage builder that can retrieve the help content from embedded text file resources in the project. If you choose to use this usage builder, you do not need to follow the steps described in this page.

Specifying Assembly* attributes

For parts of the help content, the auto-generating usage builder uses information from the Assembly* attributes, normally found in the AssemblyInfo.cs file. Specifically, it uses the values specified by the AssemblyTitle, AssemblyDescription and AssemblyCopyright attributes to build the header portion of the help content.

[assembly: AssemblyTitle("Backup Sample Application")]
[assembly: AssemblyDescription("Sample application for simple ConsoleFx applications")]
[assembly: AssemblyCopyright("Copyright (c) 2011 Jeevan James")]

After adding this code, we run the application with the "/?" argument to get the following output:

UsageAfterAttributes.png

Adding descriptions

Next, we need to add descriptive text for each option and argument that we defined earlier. To do this, ConsoleFx provides a Description method that works on both options and arguments.

For example, let's add a description for the /verbose option:

app.AddOption("verbose", "v")
    .Description("If specified, generates detailed output during the backup process")
    .Flag(() => VerboseOutput);

And for an argument, the process is exactly the same:

app.AddArgument()
    .Description("The directory to be backed up")
    .ValidateWith(new PathValidator(PathType.Directory))
    .AssignTo(() => BackupDirectory);

Similarly, once we add descriptions to all the options and arguments, we end up with something like this:

Cannot resolve image macro, invalid image name or id.

Assigning names to arguments

Unlike options, arguments do not have names
Previous: Defining the application arguments | Table of contents

Last edited Nov 24, 2011 at 8:00 PM by jeevanjj, version 7

Comments

No comments yet.