Customize command help in command line applications

Since version 0.3.0, a new section called Command example is added in the description of the commands. In this page you will learn:

• the schema of a command example and the arguments added in the command example
• the ExampleValue attribute
• how to integrate a custom validator instead of a static value and why you need it
• an example that shows how to use a static example

Schema of a command example

Since versione 0.3.0, InterAppConnector generates a command help example that shows ho to use a particular command with the minimal arguments required to execute the command. The schema of the command help is described belown

<programexecutable> <action> [-<mandatoryargumentname> "<value>" | -switch ]

where

• <programexecutable> is the name of the program
• <action> is the name of the command
• -<mandatoryargumentname> is the name of the argument. There are two types of argument supported by the library
  • arguments with values must have a value near the argument in order to be set correctly
  • switches are particual arguments that don't need a value because they are flags. If the argument is set, the relative property is set to true, otherwise remains false

For example, the string generated for a program is called UserManager with a command called adduser that requires two arguments, for instance name and age, is the one described below

UserManager.exe adduser -name "<value>" -age "<value>"

Customize the value of the argument in a command example

The command generated automatically by the library may not be very helpful. If you want to customize the values written in the example, you have two options

• use the ExampleValue attribute
• use a custm validator

First of all, the library evaluates if an argument has a custom validator and take the example value from it if exists. Then checks if the argument has an ExampleValue attribute and take the value from the attribute. If an argument does not have a custom validator or a ExampleValue attribute, the library use the value <value> as example value

The ExampleValue attribute

If the argument doesn't have a custom validator, you can use the ExampleValue attribute in order to set an example value. This attribute accepts a string as parameter.

For example, if you have a program with the argument described above and you want to customize the command help you should write something like the code described below

[ExampleValue("John")]
public string Name {get; set;} = string.Empty;

[ExampleValue("50")]
public int Age {get; set;}

If you try to execute the program, the command help will change from

UserManager.exe adduser -name "<value>" -age "<value>"

to

UserManager.exe adduser -name "John" -age "50"

You can assign only one ExampleValue attribute, and its argument must not be null or an empty string.

Use a custom validator

InterAppConnector uses also the custom valudation method in order to get the example value, and in particular retrieve the value from the GetSampleValidValue() method

If you want to learn more about how to implement a custom validator, see the page Validate argument value before command execution

You don't need to specify the ExampleValue attribute, and if you do this the attribute is ignored, as custom validator has the precedence to everything

Example

In this example, you are creating the example mentioned above from scratch

For this example it is assumed that you have learned what is a command and how to implement it. Follow these steps to complete this example:

1. Open Visual Studio, create a blank solution and name it ScoreValidator. Choose the language version (.NET 6 or above) and choose a location for your solution (for example C:\SampleProjects)

2. Create a new library project and call it ScoreValidator.Library. Then follow the steps below to complete the class library

   1. Add the InterAppConnector library as project reference

   2. Add two files to the project and call it DataModel.cs and ScoreValidator.cs. Replace the content of the ScoreValidator.cs file with the code below

      using InterAppConnector.Interfaces;
      
      namespace ScoreValidator.Library
      {
          public class ScoreValidator : IValueValidator
          {
              public object GetSampleValidValue()
              {
                  return 52;
              }
      
              public bool ValidateValue(object value)
              {
                  bool isValid = true;
      
                  if ((uint) value > 100)
                  {
                      isValid = false;
                  }
      
                  return isValid;
              }
          }
      }

   3. Replace the content of DataModel.cs with the code below

      using InterAppConnector.Attributes;
      
      namespace ScoreValidator.Library
      {
          public class DataModel
          {
              [ValueValidator(typeof(ScoreValidator))]
              public uint Score { get; set; }
          }
      }

   4. Rename Class1.cs to GetScoreCommand.cs

   5. Replace the content of GetScoreCommand.cs with the code below

      using InterAppConnector;
      using InterAppConnector.Attributes;
      using InterAppConnector.Interfaces;
      
      namespace ScoreValidator.Library
      {
          [Command("getscore", Description = "Get the score")]
          public class GetScoreCommand : ICommand<DataModel>
          {
              public string Main(DataModel arguments)
              {
                  return CommandOutput.Ok(arguments.Score);
              }
          }
      }

3. Create a new console application project and name it ScoreValidator.CLI. Then follow the steps below to complete the console application:

   1. Add the InterAppConnector library as project reference

   2. Add the UserManager.Library project as project reference

   3. Replace the content of Program.cs with the code below (CommandManager and InterAppConnector are explained in detail in Integration with console applications page)

      using InterAppConnector;
      using ScoreValidator.Library;
      
      namespace ScoreValidator.CLI
      {
          internal class Program
          {
              static void Main(string[] args)
              {
                  CommandManager manager = new CommandManager();
                  manager.AddCommand<GetScoreCommand, DataModel>();
      
                  InterAppCommunication comminucation = new InterAppCommunication(manager);
                  comminucation.ExecuteAsInteractiveCLI(args);
              }
          }
      }

4. Build the solution (you can leave the debug mode if you want)

5. Open the Command Prompt and go to the location of the executable. For instance, if you have placed your solution in C:\SampleProjects you can go to the executable by typing the above command

   cd C:\SampleProjects\ScoreValidator\ScoreValidator.CLI\bin\Debug\net6.0

6. Type the executable name with the extension (for instance ScoreValidator.CLI.exe). You should see an output similar to the one below

   -----------------------------------------------------------------------------------------------------------------------
   
   ScoreValidator.CLI 1.0.0.0
   
   -----------------------------------------------------------------------------------------------------------------------
   
   Available actions:
   
   - getscore
   Get the score
           -score (required) : No description provided
   
   Command example:
   ScoreValidator.CLI.exe getscore -score "52"

   As you can see the argument name is mandatory for the create command and optional for the delete one. Ignore the parameter description for the moment

7. Define a wrong value for the score, for example 150. Type ScoreValidator.CLI.exe getscore -score 150. You should have an error mesaage like the one below

   [10/12/2023 20:53:21] ERROR (3) : The value provided to argument score is not valid according to the validation procedure

8. Now type a correct value for the argument. Type ScoreValidator.CLI.exe getscore -score 60. You should have an error mesaage like the one below

   [10/12/2023 20:55:01] SUCCESS (0) : 60