Der NQ Core bietet einige einfache Funktionen zum Loggen von Informationen. Dieser Artikel soll Ihnen einen kleinen Einblick in die Logging-Möglichkeiten bieten.
Grundlagen
NQ Core bietet zentral Methoden zum Absetzen von Log-Nachrichten aus Services heraus. Eine Nachricht besteht aus folgenden Informationen:
- Timestamp der Nachricht
- Level
- Service-Instanz, der die Nachricht generiert
- Text der Nachricht
Nachrichten sind klassisch in mehrere Levels kategorisiert, je nachdem, wie kritisch die Information ist. Per Konfiguration kann nach einzelnen Levels gefiltert werden, um das Aufkommen an Log-Nachricht auf ein sinnvolles Maß einzuschränken.
| Level | Beschreibung |
|---|---|
| Error | Unerwartete Fehler, die u.U. die Stabilität der Anwendung beeinträchtigen können. |
| Warning | Informative Warnungen über Fehler, die sauber abgefangen werden, aber dennoch erwähnenswert sind. Dieses Level gibt es erst ab NQ Core 0.96. |
| Info | Informative Meldungen zu Abläufen in der Anwendung. |
| Debug | Meldungen, die v.a. für Entwickler hilfreich sind. |
Die Nachrichten werden auf 2 verschiedenen Wegen verteilt:
- Füllen einer Log-Datei im Benutzerverzeichnis.
- Melden von Log-Meldungen über das MessageLogged Event des Service Manager (siehe weiter unten).
Konfiguration
Die erste Möglichkeit der Konfiguration sind Kommandozeilenparameter, die an die EXE-Datei des NQ Host (nq.exe) übergeben werden können:
| Parameter | Beschreibung |
|---|---|
| -li | Aktiviert das Schreiben von Info-Log-Messages in die Log-Datei. |
| -Li | Aktiviert das Melden von Info-Log-Messages über MessageLogged Event. |
| -ld | Aktiviert das Schreiben von Debug-Log-Messages in die Log-Datei. |
| -Ld | Aktiviert das Melden von Debug-Log-Messages über MessageLogged Event. |
Standardmäßig ist im NQ Core immer das Logging von Error- und Warning-Nachrichten aktiviert, sodass mit den o.g. Parametern lediglich zusätzliche Levels hinzugenommen werden können.
Die Konfiguration der Levels kann auch programmatisch erfolgen, indem die Eigenschaften LogEventFilter bzw. LogFileFilter belegt werden:
// Events für alle Levels feuern NQServiceManager.Instance.LogEventFilter = NQLogType.All; // Nur Error- und Warning-Messages in die Log-Datei schreiben NQServiceManager.Instance.LogFileFilter = NQLogType.Error | NQLogType.Warning;
Mittels Fluent Interface ist sogar eine noch bequemere Konfiguration möglich. Im folgenden Code werden alle Levels außer dem Debug-Level in die Log-Datei geschrieben:
ServiceCore.Log.FileLevels = NQLogType.All; ServiceCore.Log.FileLevels -= NQLogType.Debug;
Wenn das Logging in die Textdatei aktiviert wurde, wird Pfad und Name im Normalfall vom NQ Core bestimmt. Der Ablageort ist das Windows-Einstellungsverzeichnis des jeweiligen Benutzers, unter Windows 7 beispielsweise
C:\Users\<Benutzername>\AppData\Roaming\NQ.<HashDesApplikationsverzeichnisses>.log
Der Dateiname enthält einen Hashwert, der aus dem Ausführungspfad der Anwendung berechnet wird. Dies dient der Unterscheidung von Log-Dateien von NQ-basieren Anwendungen, die in verschiedenen Verzeichnissen installiert sind.
Name und Ablageort der Datei können über den Kommandozeilenparameter -lf geändert werden:
nq.exe -lf C:\EinVerzeichnis\Datei.log
Abschließend seien noch Kommandozeilenparameter zeigt, mit denen Logging grundsätzlich deaktiviert werden kann:
| Parameter | Beschreibung |
|---|---|
| -ln | Vollständiges Deaktivieren der Logging-Funktionalität (per Events und Log-Datei) |
| -lni | Deaktivieren des Logging in eine Textdatei auf einem Datenträger. Bei Angabe von -ln muss -lni nicht zusätzlich angegeben werden. |
Ausgabe von Meldungen
Services können jederzeit Log-Nachrichten ausgeben, indem sie entsprechende Methoden des Service Managers verwenden:
// Log-Nachricht mit Info-Level NQServiceManager.Instance.LogMessage(NQLogType.Info, "Das ist eine Info-Nachricht"); // Log-Nachricht mit Angabe der loggenden Klasse NQServiceManager.Instance.LogMessage(this, NQLogType.Info, "Das ist eine Info-Nachricht");
Es ist auch möglich, bei Auftreten einer Exception diese direkt zum Generieren einer Log-Nachricht zu übergeben:
try
{
// Some code throwing an exception
}
catch (Exception ex)
{
NQServiceManager.Instance.LogMessage(this, NQLogType.Error, ex);
}
Das gleiche ist auch mit dem Fluent Interface möglich:
// Log-Nachricht mit Info-Level
ServiceCore.Log.Info("Das ist eine Info-Nachricht");
// Log-Nachricht mit Angabe der loggenden Klasse
ServiceCore.Log.From<object>(this).Info("Das ist eine Info-Nachricht");
try
{
// Some code throwing an exception
}
catch (Exception ex)
{
ServiceCore.Log.From<object>(this).Error(ex);
}
Benutzerdefinierte Behandlung von Log-Messages
Wie bereits erwähnt, ermöglicht der NQ Core Services auch eine eigene Behandlung von Log-Nachrichten. Dazu dient das Event MessageLogged:
NQServiceManager.Instance.MessageLogged += ServiceManager_MessageLogged;
…
void ServiceManager_MessageLogged(object sender, NQLogEventArgs e)
{
// Anzeige einer MessageBox bei Error-Logs
if (e.LogType == NQLogType.Error)
{
MessageBox.Show(e.LogMessage, Application.ProductName,
MessageBoxButtons.OK, MessageBoxIcon.Exclamation);
}
}
Eine besondere Eigenschaft betrifft die Log-Nachrichten, die vom Service Manager selbst erzeugt werden. Viele dieser Nachrichten werden nämlich schon erzeugt, bevor überhaupt ein Service aktiv wird. Damit Services auch diese Nachrichten mitbekommen, werden sie während der Startup-Phase vorübergehend gecached. Erst wenn alle Single-Instance-Services geladen und aktiv sind, werden diese zwischengespeicherten Nachrichten “auf einen Schlag” per MessageLogged Event verteilt.
