Console Application. RunCmd Utility
Table of contents
- DB Connection
- Command-Line Keys
- Error Handling
For the successful use of RunCmd.exe tool, it is important to configure it correctly for the needs of a particular application. By default, the utility uses the RunCmd.exe.config file, but it is possible to specify another config-file (similar to DBUpdater). /appconfig key allows to specify config-file (all command line keys are described below). The most important sections of the configuration file are securityConfiguration, connectionStrings and applicationSettings.
Security settings must be specified in the <securityConfiguration> section. Because the RunCmd is a complementary tool for some XAF application, then executable Commands interact with the application database. Therefore, utility must support the same authentication mechanism as the main application.
The concept of authentication mechanism consists of the following important elements:
- Authentication classes, for example: AuthenticationStandard, AuthenticationActiveDirectory, XafariAuthentication
- User classes: SecuritySystemRole, SecuritySystemUser, Xafari.Northwind.Security.InheritedRole, Xafari.Northwind.Security.InheritedUser
- Types of the logon parameters:XafariAuthenticationLogonParameters
All of the above-mentioned types are included in the application security system, they are contained in certain assemblies. Developer must specify this assemblies in securityAssemblies property, list the names of assemblies, separating them with a semicolon. If these assemblies are XAF-modules, it is also required to specify them in the Modules key of the <appSettings> section.
If necessary, it is possible to specify a particular implementation of roles and users classes, roleTypeName and userTypeName keys are intended for these purposes. Class name must be specified with a namespace. RunCmd will use specified values to initialize SecurityStrategyComplex.RoleType and SecurityStrategyComplex.UserType properties.
typeName property of the <authentificationClass> section describes authentication class, specify namespase and class name. RunCmd will create an instance of the specified class and will use it to initialize SecurityStrategyComplex.Authentication property. When creating the authentication class instance, framework may require to initialize certain properties of this class.To specify corresponding values, there is special <properties> subsection within <authentificationClass> section. Use <add name="…" value="…"> for every new item. All values will be processed by utility.
System.ComponentModel.TypeConverter.ConvertFromString method in utility code generates values according to the type of initialized properties. When generating System.Type property, utility will use the class specified in the value for the instance creation.
Specify the connection string in the <connectionStrings> section by analogy with the main application.
Set DbApplicationName parameter in the <applicationSettings> section, specify the name of the main application that works with database, this name is required to check the compatibility of the database.
All modules that contain the implementation of Commands should be listed in the <appSettings> section.
When first start the RunCmd.exe, incompatibilities with the database exception may occur. If this occurred run the command to update the database, which is integrated into the utility. To do this, use the /dbupdate command line key, it is described below.
DevExpress supplies DBUpdater tool to update the database, but on a new DB with RunCmd.exe it works incorrectly. If the database has already been used, then to lead the database to a consistent state DBUpdater can be used successfully.
1. General Information
To display a brief help for the RunCmd.exe utility, use any of the following keys:
To obtain a list of available commands, run the utility with the following keys:
To learn the parameters of the certain Command, run the utility with the following keys:
Command execution. Specify Command name and parameters, separate the parameter value from its name using ":" symbol. The valid notations are:
/command <comand_name> <parameter_1>:<value_1> <parameter_2>:<value_2> <parameter_3>:<value_3> ...
/c <comand_name> <parameter_1>:<value_1> <parameter_2>:<value_2> <parameter_3>:<value_3> ...
If the Command is a first argument in console, then the key /command or /c can be omitted.
It is possible to specify multiple Commands in the RunCmd command line. In this case they will all be executed in the order in which you have them listed.
2. Using File
It is possibile to pre-define a list of Commands in a text file, and then specify its name in the key:
Each Command with its own parameters takes one line in a text file. Command must be in the following form:
<1_comand_name> <parameter_1>:<value_1> <parameter_2>:<value_2> <parameter_3>:<value_3> ...
<2_comand_name> <parameter_1>:<value_1> <parameter_2>:<value_2> <parameter_3>:<value_3> ...
Note the keys that must be used to specify the authentication parameters:
/logon <parameter_1>:<value_1> <parameter_2>:<value_2> …
/l <parameter_1>:<value_1> <parameter_2>:<value_2> …
Pairs in the form <parameter_x>:<value_x> describes parameters and its values. Utility interprets these pairs as the names and values of properties of a class that describes a logon-parameters. For example, properties of a XafariAuthenticationLogonParameters class. The utility creates an instance of the logon-parameters class, sets its properties to the values specified on the command line, and then uses the instance when authenticating.
The /logoff key is intended to end the session of the authenticated user. This key demand when using the interactive mode (see below.), it will allow to execute Commands under different users.
If there is a mismatch with the database, use the key
This will entail standard procedure to verify compatibility of the database and to performed the update. Optional silent allows you to upgrade without user intervention.
To use the utility in interactive mode, run it with the following key:
Then it starts in an interactive mode, it will print to the console commands prompt and will wait for user action. To enter a Command, use <Enter>, to exit from interactive mode use the "exit" or "quit" commands or Ctrl+Break and Ctrl+C keyboard shortcut.
The application is initialized only one time at the start of the utility. This mode allows to perform multiple Commands sequentially, without wasting time waiting for the application initialization. Interactive mode can be used to execute Commands from different users (see. /logon and /logoff keys above).
To specify a config-file other than RunCmd.exe.config, use the following keys:
<file name> specifies the path to the config-file.
/basedir specify the directory with the required assemblies. If /basedir not specified, the search for the necessary assemblies will be made in the directory location of the config-file.
RunCmd returns the ERRORLEVEL integer code which specifies the status of the command execution. A value of zero indicates successful execution, any value other than zero indicates an error. Thus command-line utility reports the status of execution to interoperate with other programs or scripts.
For instance, the snippet below demonstrates a batch file, which parses the command status:
RunCmd.exe /appconfig Xafari.BCDemo.Win.App.exe.config /s /logon AuthenticationType:ActiveDirectory
@if "%ERRORLEVEL%" == "0" goto good
echo Execution Failed
echo return value = %ERRORLEVEL%
echo Execution succeeded
echo Return value = %ERRORLEVEL%
By default, RunCmd handles all runtime exceptions. There is standard RunCmd.log file to store information about exceptions. Brief information about the error is displayed in console window.
However, if necessary, RunCmd can generate an exception if an error occurs. To enable this mode, add ThrowExceptions key to the appSettings section of the RunCmd.exe.config file and set this key to "True".