Advanced programming

collapse
  • Scope /
  • Advanced programming
Introduction

The iPlus notification system offers the following functionalities:

  • Logging in temporary log files.
  • Hierarchical alarm system with database storage.
  • Display messages in dialogs and user queries.
  • Uniform use in web services (SOAP, JSON).
  • Multilingualism.

The message component

The property "IRoot  ACRoot" of an ACComponent points to the root component iPlus in the entire application tree. In your ACComponentChilds list there is an instance with the ACIdentifier "Messages" of the type  IMessages. 

IMessages offers a variety of methods to log messages and open dialogs in the user interface. 

The IACComponent interface provides the property "Messages" so that the application programmer does not have to cumbersome access to the message instance.
IMessages messageService = (IMessages) ACUrlCommand("\\Messages");


Message log

The message log is a text file that is located in the temporary user directory:

>cd %USERPROFILE%\AppData\Local\Temp

The format of the file name and the filter settings which messages are to be output are controlled via the application configuration file (App.config or * .exe.config in the bin directory):

In step 1 (see above),  the iPlus configuration class LoggingConfiguration from the namespace "gip.core.autocomponent" must be announced using <sectionGroup> and <section> .

In step 2, then the classes LoggingConfiguration, LogFileElement, LoggingTypeElement can be used. 

The list <LoggingTypes> contains Entries of type "gip.core.autocomponent.LoggingTypeElement" which are added by the <addLoggingType>-Element. This class is used to describe which messages, that occur using IMessages, should be filtered and not output. With each entry a new "log file type" is defined which must be given a unique name in the "FileType" attribute.

The entries in the <LogFiles> list that are added via <addLogFile> then refer to this "log file type". The entries are of the type "gip.core.autocomponent. LogFileElement". This declares which log files are written with which file name.

 

LoggingTypeElement (Section <addLoggingType>):

Namedescription
string FileType

Unique name of the "log file type".

string MessageTypeFilter that specifies what type of messages should be considered. The possible values ​​are defined in the "gip.core.datamodel.eMsgLevel" enum: Default, Debug, Info, Warning, Failure, Error, Exception, Question. With "Default" no messages are filtered and all are output. 
string SourceFilter (ACUrl) that specifies from which ACComponent instance messages are to be output. With "*" all instances are taken into account.
string ACName

Additional filter that only takes into account messages for which the property gip.core.datamodel.Msg.ACIdentifier matches. The ACIdentifier is any string that can be assigned by the programmer. It is primarily used to find the correct code in the program code. It is advisable to specify the method name with a unique code number, eg. "Start(50)".

bool DumpThreadIDIf "True", then the ThreadID is written in the log lines.
string Smtp

Connection parameters to send messages via SMTP. Parameters are declared separated by semicolons: 

SmtpServerHost=localhost;
SmtpServerPort=25;
SmtpUseSSL=false;
IgnoreInvalidCertificate=true;
SmtpAuthUser=iPlus;
SmtpAuthPassword=iPlusPW;
SmtpFrom=iPlus@localdomain.com;
SmtpReceipients=rcp1@localdomain.com,rcp2@localdomain.com;

The System.Net.Mail.SmtpClient class is used for sending. 

 

LogFileElement (section <addLogFile>):

Namedescription
string FileType

Reference to the log file type defined in the <addLoggingType> section.

string FileNameFile name of the log file. With placeholder %Date% the current day is inserted in the format "YYYYMMDD". %ProcessId% inserts the process ID.
int MaxSizeMBMaximum file size in MB.
int ArchiveAfterDaysIf the value is> 0, log files that are older than the specified value are added to a ZIP archive.

Output messages

There are numerous methods for outputting messages that begin with the "Log" prefix. e.g. LogDebug, LogInfo, LogWarning, LogException ...

LogDebug calls an internal method and passes gip.core.datamodel.eMsgLevel.Debug:

public void LogDebug(string source, string acName, string message)
{ LogMessage(eMsgLevel.Debug, source, acName, message); }

So it is with the other methods with the endings Info, Warning, Failure, Error and Exception.

 


The Msg class

IMessages offers another method with the following signature:

public void LogMessageMsg(Msg msg)

The parameter "msg" is of the type " gip.core.datamodel.Msg" . The use of Msg has the following advantages :

  • Multilingualism: Messages are translated into the language of the registered user.
  • Information about the message type eMsgLevel. This makes it easier for the recipient to assess how important or critical this message is. For this reason it is recommended to replace methods with a boolean return value with Msg as return value.
  • Serializable. The message can be distributed to other clients in the network or used for iPlus' SOAP or JSON service.
  • Alarm handling: Lists of pending messages can be displayed and acknowledged in the control dialog. In the alarm explorer, alarms can be grouped and sorted according to their frequency.
  • Msg can be derived in other message classes to add your own logic. For example, "gip.core.datamodel.MsgWithDetails" is such a class that itself has a list of Msg instances, for example to collect many error messages that have appeared during a long operation. On the one hand, this list can be displayed on the surface and on the other hand the recipient can evaluate all error messages.
  • Msg can be expanded to include virtual fields that are serialized in XML. This means that additional information can be saved for specific projects and displayed in the alarm lists.

 

Namedescription
Guid MsgId

Unique ID

eMsgLevel MessageLevelImportance of the message: The possible values ​​are: Default, Debug, Info, Warning, Failure, Error, Exception, Question
string SourceACUrl of the ACComponent instance that generated this message.
string ACIdentifierThe ACIdentifier is any string that can be assigned by the programmer. It is primarily used to find the correct code in the program code. It is advisable to enter the  method name  with a  unique code number, e.g. "Start (50)"
string MessageMessage text. This is either set manually or indirectly via the translation table:
string TranslIDUnique text ID stored in the ACIdentifier field in the ACClassMessage table. ACClassMessage contains all of the translated message texts (in the "Translation tuple" format). This ID is used to access the text to be translated with which the "Message" property is set.
DateTime TimeStampOccurredTime of the notification event
DateTime TimeStampAcknowledgedTime of user confirmation.
string AcknowledgedByName of the user who confirmed the message.
ACRef < IACComponent > SourceComponentReference to the instance that generated the message.

 

 


Translate an manage message texts

Message texts are managed under menu item "? -> Development environment".
Navigate there to the class for which you need a new message. Open the "Translation" tab and click on one of the "New ..." buttons:

A new message ID is generated and a new entry is made in the ACClassMessages table. Translate the texts and save the changes.

Important: Message texts are inherited! Therefore, always create the message text in the appropriate class and not in a derivation or virtual derivation.


Show messages in dialogs

In order to display message boxes or modal dialogs with a message, the IMessage interface provides methods that begin without the "Log" prefix.  

With "enum gip.core.datamodel.eMsgButton" you can control which keys are displayed (OK, Cancel, Yes, No).

Which button the user has pressed is indicated by the return value of the methods of the type "enum  gip.core.datamodel.Global.MsgResult". 

Here are a few examples: