Console, Operations and Console plug-ins

Console

The Consoles are the main building blocks of an imbACE Application. Although they are primarily used for the Console Application user interface, they also may be blended into Terminal Application using proper screen wrapper class. A Console class contains a set of embedded Operations, Console Plug-ins and properties.

To create your Console, declare your class that inherits one of two bases:

  • aceCommandConsole
    • beside few basic commands (like: help, exportHelpThe command will export an auto-generated help file (Markdown) to the specified filename in currents console session (called state) path. If filename is not specified, it will be: "help.txt". Example: ExportHelp filename="help.txt";open=True;onlyThisConsole=False; open - will try to open the generated file with Notepad++ onlyThisConsole  - it will export only commands at the current level of class type, it will not..., cls, exit…) it is also capable loading and executing an external ACE Script (commands: executeScript, templateScript).
  • aceAdvancedConsole
    • has its own State class (i.e. project, job, task settings…) and its own Workspace (i.e. dedicated directory and application specific input/output methods)

The console application may have a number of Consoles, where the Main Console is the one that is started with application boot.


Operation

The Operations are actually public methods of a Console class, declared according the proper name pattern:

public [return type] aceOperation_[group][name]([command arguments])

Console Operations may be executed/called from:

  • command-line arguments, if the host Console is the Main console of an imbACE Application
  • command line user interface of a Console Application
  • ACE Script
  • a menu item of a Terminal Application
  • or other parts of your C# code

The easiest way to add an operation to your console class is to use snippet _aceOperationMethod, that will declare new method with three arguments, with both XML documentation and proper attributes. Below is an example of operation method, which is an actual operation declared at aceCommandConsole base class:

[Display(GroupName = "run", Name = "Pause", ShortName = "", Description = "It pause ACE script execution, optionally displays custom message and allows user to end the pause")]
[aceMenuItem(aceMenuItemAttributeRole.ExpandedHelp, "If wait set to -1 there will be no time limit, the user will have to stop it. It will beep in last 1/5 of wait period.")]
/// <summary>It pause ACE script execution, optionally displays custom message and allows user to end the pause</summary> 
/// <remarks><para>If wait set to -1 there will be no time limit. If userCanEnd is true it will allow user to end the pause and continue.</para></remarks>
/// <param name="wait">How log the pause may last? in seconds. If set to -1 there is no time limit</param>
/// <param name="msg">Custom message to be displayed to user.</param>
/// <seealso cref="aceOperationSetExecutorBase"/>
public void aceOperation_runPause(
    [Description("How log the pause may last? in seconds. If set to -1 there is no time limit")] Int32 wait = 60,
    [Description("Custom message to be displayed to user.")] String msg = "")
{
    if (msg == "")
    {
        msg = "Pause command called";
    }

    aceTerminalInput.askPressAnyKeyInTime(msg, false, wait, true, wait / 5);
}

The attributes and their purpose in the context of console operation declaration:

  • Display.GroupName
    • The group is used to categorize operations when displayed in console help content, either: it is on-screen help, command-line help or exported help document
  • Display.Name
    • Name is the operation command-line name, used in both console input and ACE Script
  • Display.ShortName
    • Short name (alias with: aceMenuItemAttributeRole.Key) defines the shortcut key when the operation is rendered as menu item or called from command line arguments.
    • When the shortcut is shift + a letter, you simply specify it as capital letter, e.g. “K” instead of “k”
    • It also supports modifier keys, then specified in format like: “CTRL+p”, “ALT+q” or “CTRL+ALT+p”
  • Display.Description
    • Description is the first line of help content displayed under operation definition. It should provide an in-sight on purpose of the operation.

With aceMenuItemAttribute you are able to provide additional meta information on the console operation. For that purpose the role enumeration is used, where the most useful are:

  • aceMenuItemAttributeRole.ExpandedHelp
    • Additional help content line, displayed in extended help content. It should describe what will operation actually do, once it is called.
  • aceMenuItemAttributeRole.ConfirmMessage
    • This flag does two things: it tells the interpreter to prompt user for confirmation before executing the operation code and defines message that should be asked
    • The user will be prompted with Yes/No dialog, displayed in form according to application’s interface settings

Console plug-ins

The way to nest additional operations in a console class, and to have their code re-usable across different consoles, is to define a custom console plugin. You may declare your custom console plugin class from the basic class or from some extended plugin base classes, such as: aceConsolePluginForFiles.

To make a plugin available at a console by default, just declare a public property within your console class.  In the example code below, we have a public property for custom plugIn_dataLoader, implemented with lazy initialization:

public myConsole:aceCommandConsole {

private plugIn_dataLoader _analytics;
[Display(Description = "A custom console plugin for post-processing of exported DataTable files")]
/// <summary>
/// A custom console plugin for post-processing of exported DataTable files
/// </summary>
public plugIn_dataLoader analytics
{
    get {

        if (_analytics == null) _analytics = new plugIn_dataLoader(this, nameof(analytics));
        return _analytics;
    }
}

...

}

Proper call to its operation named “RecoverTime” from command line or ACE Script is:

analytics.RecoverTime;

See also:

Attachments

  • Advanced Console Class
    Item Template for Visual Studio: Advanced Console, State and Workspace classes
    File size: 102 KB Downloads: 350
  • Console Application Project Template
    Project Template for Visual Studio: Class inheriting aceConsoleApplication and custom Advanced Console, State and Workspace classes.
    File size: 105 KB Downloads: 325
Spread the love