Typischerweise werden Anwendungsprotokolle von den Hintergrundprozessen geschrieben, prinzipiell können sie aber an beliebige Stellen genutzt werden. Die Anwendungsprotokolle haben eine gemeinsame Basis-Datentabelle (Basis.Anwendungsprotokoll / OrmLogBase). Daher kann man eigene Datentabellen davon ableiten und bestehende erweitern. Eine konkrete Datentabelle Anwendungsprotokoll / OrmLogDefault ist ebenfalls vorhanden. Diese kann genutzt werden, wenn keine speziellen Eigenschaften benötigt werden.

Anwendungsprotokolle sollten nicht mit einer UnitOfWork erstellt werden, stattdessen sollte es eine eigene Session haben, so dass fehlgeschlagene Transaktionen das Protokollieren nicht verhindert.

Erstellen / Speichern

Ein Protokoll wird identisch wie die anderen Datensätze erstellt. Der Inhalt wird automatisch gespeichert, wenn Einträge hinzugefügt werden. Direkt nach dem Erstellen könnte man es speichern, um sicherzustellen, dass es vorhanden ist. Ansonsten sollte man den Hauptdatensatz des Protokolls nicht mehr speichern. Das Hinzufügen von Einträgen ist thread-safe und ohne LockingExceptions. Daher keine Aufrufe von Save() während der Protokollierung!

Worker

Innerhalb eines Workers wird das Protokoll vom System erstellt und verwaltet, man sollte lediglich den Prozess auf den Auswahlwert EnumLogProcesses seines Prozesse setzen.

LoggingProcess =  EnumLogProcessesExtension.MyLog;

Wird eine eigene Log-Datentabelle gewünscht. Setzt man dazu im Konstruktor seines Workers die Guid der Log-Datentabelle, bzw. überlädt auch InitLogger().

public MyWorker() : base()
{
    ...
   LoggingMode = WorkerLoggingMode.Always;
   LoggingProcess =  EnumLogProcessesExtension.MyLog;
   LoggerGuid = EnumDataSource.MyLogGuid;
    ...
}
protected override void InitLogger()
{
    base.InitLogger();
    // set properties
    Logger.Title = "My Title";
    SetEnumValue(nameof(OrmLogBase.Process), LoggingProcess);
}

Protokollsprache

In den Anwendungseinstellungen wird die “Inhaltssprache für Protokollierung” festgelegt. Daher muss man darauf achten nicht die üblichen Übersetzungsmethoden String.Translate() und Api.Text zu verwenden.

Die eigentlichen Api Methoden übersetzen selbst. Zusätzlich ist auf OrmLogBase eine entsprechende Translate() Methode vorhanden.

Protokolleinträge

Als Standard Api stehen folgende Methoden zur Verfügung.

public void AddInfo(string text, params object[] para)
public void AddWarning(string text, params object[] para)
public void AddError(string text, params object[] para)
public void AddFatal(string text, params object[] para)
public void AddDebug(string text, params object[] para)

Mehrzeilige Einträge dürfen nicht mit mehrfachen Aufruf der Add Methoden erzeugt werden, da die Auswertung dadurch erheblich erschwert wird. Stattdessen wird es mit \n Mehrzeilig gestaltet.

Beispiel:

Logger.AddInfo("Text mit {0} {1}", 2, "Platzhalter");
Logger.AddInfo("[INSERT TRANSLATION GUID]", 2, "Platzhalter");
Logger.AddInfo("Zeile 1\nZeile 2\Zeile 3");

LogExcpetion

Die Ausnahme LogExcpetion kann genutzt werden, um Informationen für Protokolleinträge zu werfen.

throw new LogException(EnumLogLevel.Warning, "[INSERT TRANSLATION GUID]");

Die entsprechend abgefangen werden muss.

catch (LogException logException)
{
    logger.AddEntry(logException);
}

Einrückungen im Protokoll

Einrückungen im Protokoll dienen für die Strukturierung und damit zur besseren Lesbarkeit. Beim Aufruf von CreateSubEvents() erhält man als Ergebnis einen Helper, der den Kontext bis zu seinem Dispose-Aufruf aufrecht erhält. Typischer Anwendungsfall:

Logger.AddInfo("Starting work XXX");
using (Logger.CreateSubEvents())
    foreach (wasauchimmer)
    {
        Logger.AddInfo("Jetzt bei YYY");
    }

Solche Kontexte können geschachtelt werden.

Es ist allerdings nicht zulässig, die Einrückung zu erhöhen, ohne vorher ein Event erzeugt zu haben. Alle neuen Einträge innerhalb des Sub-Entries-Kontextes werden zum letzten Event davor zugeordnet.
Im Besonderen sollte das nicht verwendet werden, um ein zusammengehöriges, mehrzeiliges Event zu ersetzen.

Falls die Protokollierung in dasselbe Log über verschiedene Log-Instanzen erfolgt, hat jede ihren eigenen Einrückungskontext. Dieser wird nicht gespeichert. Immer wenn ein Log neu geöffnet wird, um Einträge hinzuzufügen, beginnt man wieder im Top-Level.