Services

Die Basisklasse einer Bausteinimplementierung bietet einen Abschnitt Services mit der verschiedene Informationen und Dienste angesprochen werden können. Nachfolgend sind die Gruppen von Themen beschrieben.

Der Abschnitt Application (zugrundeliegender Typ ist ApplicationInfo) bietet Unterstützung bei anwendungsbezogenen Informationen und Funktionalitäten. Siehe die Beschreibung der Klasse ApplicationInfo für Details. Zusätzlich steht eine Methode ApplicationInfo zur Beschaffung von Informationen zu anderen Anwendungen zur Verfügung.

ApplicationInfo ApplicationInfo(ApplicationEnum app)

Die Methode ApplicationInfo liefert die Informationen zu einem anderen als die für den Baustein definierte Anwendung. Das ApplicationEnum Argument gibt dabei an, für welchen Baustein man weitere Informationen haben möchte. Die möglichen Werte für ApplicationEnum entsprechen die in der Assembly benutzten Anwendungen. Der Rückkehrwert entspricht die Klasse ApplicationInfo wie diese auch für die Eigenschaft Services.Application festgelegt wurde.

Persistency CreatePersistency();

Mit der Methode CreatePersistency können beliebige Instanzen der Persistency-Klasse angelegt werden. Hiermit können Objektdaten sitzungsübergreifend gespeichert und wiederhergestellt werden.

Der Abschnitt Logger bietet Unterstützung für die Erstellung eines fachlichen Logs.

Es können Einträge in die Logdatei mit unterschiedlichen Kennzeichnungen gemacht werden. dafür stehen folgende Methoden zur Verfügung:

Exception Debug(String message);
Exception Performance(String message);
Exception Info(String message);
Exception Warning(String message);
Exception Error(String message);
Exception Fatal(String message);

Falls die Logeinträge nicht geschrieben werden können, wird dazu eine Exception erzeugt, die jedoch nicht aufgeworfen wird. Auch wenn bei der Erstellung der Logeinträge sonstige Ausnahmen auftreten, werden diese abgefangen und nicht aufgeworfen. Das alles damit die Log-Einträge den normalen Ablauf nicht beeinträchtigen. Deswegen werden die Logeinträge auch nicht direkt auf dem ausführenden Thread erstellt und geschrieben, sondern werden im Hintergrund erst bei entsprechendem Leerlauf verarbeitet. Am Ende des Prozesses werden ggf. noch ausstehende Einträge nachgeholt.

public LogPerformance Measure(String message)

Mit der Methode Measure können Messungen über Code-Abschnitte vorgenommen werden. Diese Methode liefert ein Disposable Objekt zurück. Beim Aufräumen des Objektes wird die angegebene Meldung in die Logdatei eingetragen, gefolgt durch die Zeitspanne zwischen Instanziierung und Dispose des Objektes. Wenn die Meldung eine Formatanweisung mit dem Platzhalter {0} ist, wird stattdessen die Anzahl Millisekunden in diesem Platzhalter ausgefüllt.

using (Module.Services.Logger.Measure("Waiting for resume")) {
	Module.Yield(this, YieldStrategy.DisableKind.HideAndShow);
}
 
using (this.Services.Logger.Measure("Test Logger was {0:#,##0}ms in MyModule.MyMethod")) {
   MyModule.MyMethod();
}

Die Sourcedatei und die Zeile, an der die Eintragung veranlasst wird, wird automatisch dem Log-Eintrag hinzugefügt. Die Logdatei wird pro Geschäftsvorfall im XML-Format erstellt. Zum Beispiel erzeugt folgender Code

if (gevostatus.Contains(gevor.GstGevoStArtK, gevor.GstGevoStArtRst)) {
	this.Services.Logger.Info(gevostatus[gevor.GstGevoStArtK, gevor.GstGevoStArtRst].GevoStKbz);
}

folgende XML-Einträge:

<?xml version="1.0" encoding="utf-8" ?>
<LogEntries EnvSpec="ALREWT" BcApplAbbrev="" BcShortname="" BcId="" BcGuid="{BE3CA163-7A97-43B4-B8CC-0C86FE140A3A}">
...
<LogEntry Date="2015-10-14 17:08:21" Severity="Info" Source="d:\work\edb\sample\gen\UseTestCases\Funcs\HgUrlEckdaten.cs" Line="36" ThreadId="5">
  <Message>WvlE</Message>
</LogEntry>
...
</LogEntries>

Die einzelnen Einträge erhalten einen Tag mit dem Namen LogEntry, als Wert den anwendungsseitig vorgegebenen Text und als Attribute Date für Datum und Uhrzeit, Severity für die Art der Meldung, Source für die Quelldatei, Line für die Zeilennummer und ThreadId für den aktuellen Thread.

Alle Meldungen sind unter einem übergeordneten Element mit dem Tag LogEntries gruppiert. Dieses Element erhält die Attribute EnvSpec für die aktuelle Umgebungsangabe, BcApplAbbrev mit dem Kürzel der Anwendung zu der der Geschäftsvorfall gestartet wurde, BcShortname mit dem Kürzel, BcId mit dem ID und BcGuid mit dem Guid des Geschäftsvorfalles. Im Falle eines technischen Geschäftsvorfalles sind BcApplAbbrev, BcShortname und BcId leer.

public String Filename { get; }

Der Name der Logdatei wird vom TAA Administrator vorgegeben und liegt im systemdefinierten Verzeichnis für Temporäre Dateien. Der konkrete Name der Logdatei kann über die Eigenschaft Filename abgefragt werden.

Exception Log(Exception exception);

Als Sonderfall kann eine Exception in die Logdatei eingetragen werden. Ein derartiger Eintrag wird als Exception Element unterhalb des LogEntry-Elementes eingetragen. Die relevante Eigenschaften (Type, Source, Data, Stacktrace) werden als Attribut festgehalten, die Message als Text. Für SqlException und ComException werden untergeordnete Elemente mit spezifischen Angaben (ErrorNumber, ServerName, Procedure, ErrorCode) festgehalten. Auch eine AggregateException wird rekursiv aufgelöst.

<LogEntry Date="2015-10-14 17:43:16" Severity="Exception" Source="d:\work\edb\sample\gen\UseTestCases\Funcs\HgUrlEckdatenPruefen.cs" Line="77" ThreadId="10">
  <Exception Type="TeamWiSE.Runtime.Common.Condition" Source="TeamWiSE.Runtime.Common.ConditionsChecker.Dispose">
    <Message>Warning ZZTAAOM1(0): Keine Berechtigung für verlangte Operation ( HGUSTEU(1)/Put/REF). [Object: HGUSTEU, Index: 1; HG-URL-ECKDATEN-PRUEFEN.PRUEFEN(0), Ispc: &lt;D:\work\edb\sample\gen\UseTestCases\bin\Release\UseTestCases.exe;UseTestCases.Funcs.HgUrlEckdatenPruefen;Execute;Y&gt;, EnvSpec: ALREWT, Plattform: LAN ; Caller: ; 2015-10-14-17.43.15.303000]</Message>
    <Data>
      <Entry Key="INHALT" Value="REF" />
      <Entry Key="INDEX" Value="1" />
      <Entry Key="OBJEKTNAME" Value="HGUSTEU" />
      <Entry Key="AUFRUFER" Value="HG-URL" />
      <Entry Key="OPERATION" Value="Put" />
      <Entry Key="PLATTFORM" Value="LAN" />
      <Entry Key="ENVSPEC" Value="ALREWT" />
      <Entry Key="ISPC" Value="D:\work\edb\sample\gen\UseTestCases\bin\Release\UseTestCases.exe;UseTestCases.Funcs.HgUrlEckdatenPruefen;Execute;Y" />
      <Entry Key="TAASRC" Value="d:\work\dll32\trt\taaomfmt.cpp" />
      <Entry Key="TAALINE" Value="7010" />
    </Data>
    <StackTrace>   bei TeamWiSE.Runtime.Common.ConditionsChecker.Dispose() in d:\work\dll32\cct\Runtime\Common\ConditionsChecker.cs:Zeile 97.
   bei TeamWiSE.Runtime.Internal.CoreApi.taaOm.ObjPutFld(Module module, HTAAOMOBJITEM hRec, String Name, ItemDefinition Definition, Object Value, UInt32[] idxs) in d:\work\dll32\cct\Runtime\Internal\CoreApi\taaOm.cs:Zeile 147.
   bei TeamWiSE.Runtime.NativeSupport.DataObject.SetField(Int32 idx, Object value, UInt32[] idxs) in d:\work\dll32\cct\Runtime\NativeSupport\DataObject.cs:Zeile 227.
   bei Tw.TwonlyTest.Dsto.Twonly.Twhgus.&lt;get__000DubOpcod&gt;b__1(UInt16 value) in c:\T\TwonlyTest\Dsto\Twonly\HgUrlSteuerdaten.cs:Zeile 86.
   bei TeamWiSE.CommonControls.Runtime.NativeSupport.Domain`1.set_Value(T value) in d:\work\dll32\cct\Runtime\NativeSupport\Domain.cs:Zeile 97.
   bei UseTestCases.Funcs.HgUrlEckdatenPruefen.MyMethod() in d:\work\edb\sample\gen\UseTestCases\Funcs\HgUrlEckdatenPruefen.cs:Zeile 73.</StackTrace>
  </Exception>
</LogEntry>

Der Abschnitt Monitor bietet Hilfen zum Umgang mit dem TAA-Monitor.

UInt32 LevelOfDetail { get; set; }

Diese Eigenschaft gibt an, wie viele Meldungen im TAA-Monitor ausgebeben werden sollen. Je höher der Wert, desto detailliertere Meldungen werden ausgegeben.

Ausgangswert ist der in der TAA-Registry als InfoLevel eingestellte Wert. Dieser Wert lässt sich nicht nur abfragen, sondern auch dynamisch zur Laufzeit ändern. So können bspw. problematische Stellen mit entsprechendem Code umklammert werden:

var oldlevel = Services.Monitor.LevelOfDetail;
Services.Monitor.LevelOfDetail = 5;
try {
	// some complex code that needs more info
}
finally {
	Services.Monitor.LevelOfDetail = oldlevel;
}

void Send(String message)

Diese Methode sendet den angegebenen Text als als Anwendernachricht an den TAA-Monitor, wo er angezeigt wird, sofern Nachrichten des Typs User-defined Trace and Information aktiviert sind.

void Oops(String Message [, String source, Int32 line])

Oops-Meldungen sind Nachrichten, die je nach TAA-Umgebungseinstellungen im Monitor, in Log und/oder in Meldungsboxen ausgegeben werden. I.d.R. weisen Oops-Meldungen auf unerwartete Situationen im Anwendungsablauf hin, die zwar nicht zum Anwendungsabbruch führen, aber dennoch bemerkt werden sollten.

Um für einheitliche Behandlung solcher Situationen zu sorgen, können Sie statt Oops-Meldungen auch Conditions verwenden.

Die Argumente Source und Line werden normalerweise nicht angegeben, sondern automatisch vom Compilr ergänzt. Alternativ kann man auch eigene, abweichende Angaben machen.

Folgender Code führt zu nachfolgende Ausgabe an den TAA-Monitor:

if (Services.Monitor.LevelOfDetail > 0) {
	Services.Monitor.Send("Hello World!");
	Services.Monitor.Oops("Hello again");
}

User     9412  /10264 : Hello World!
OopsEntr 9412  /10264 : d:\work\edb\sample\Module\DllClrNative\TC_OBJFLD_DLLCLR.cs(276): Hello again  (TC-OBJFLD-DLLCLR.DURCHFUEHREN) (SAMPLE.818) [0x038a760c (SAMPLE.TC-NTRY)/{B09D84ED-4260-47B1-94BB-DCF9876AFB7D}/9412/V8.18.3.2618]

Man beachte, wie die Source und Line Argumente automatisch ergänzt wurden.

public String Filename { get; }

Pfadangabe zur Speicherung von Oopsmeldungen. Wenn Oopsmeldungen nicht in einer Datei gespeichert werden, ist diese Angabe leer.

Der Abschnitt Timestamp bietet diverse Methoden und Eigenschaften zur Unterstützung für Datum- und Uhrzeit-bezogene Funktionalitäten. Wichtig dabei ist, dass diese Methoden und Eigenschaften den Kontext des aktuellen Bausteins berücksichtigen, und so bspw. die Einstellungen für den TimestampOffset berücksichtigen. Einige Methoden und Eigenschaften können auch unabhängig vom Kontext des aktuellen Bausteins benutzt werden. Diese sind dann alternativ als Methoden und Eigenschaften an der statischen Klasse TeamWiSE.Runtime.Common.TimestampServices verfügbar.

public DateTime Now { get; }

Ruft ein DateTime-Objekt ab, das auf das aktuelle Datum und die aktuelle Zeit auf dem lokalen Rechner als lokale Zeit festgelegt ist. Die Präzision ist in Millisekunden. Der Mikrosekundenbereich wird benutzt um die gelieferte DateTime innerhalb des aktuellen Geschäftsvorfalls eindeutig zu halten. Die Einstellung am TimestampOffset werden berücksichtigt.

public DateTime Today { get; }

Liefert das gleiche wie Now, aber mit einer auf 00:00:00 festgelegten Zeitkomponente.

public static DateTime MinDate { get; }

Das kleinstgültige Datum, derzeit immer 01.01.1000.

public static DateTime MaxDate { get; }

Das höchstgültige Datum, derzeit immer 31.12.9999.

public static bool IsMinDate(DateTime value)
public static bool IsMaxDate(DateTime value)
public static bool IsMinOrMaxDate(DateTime value)

Prüfungen zur Feststellung, ob ein bestimmter Datumswert das kleinstmögliche, größtmögliche Datum oder eines von beiden entspricht.

public static DateTime MinTimestamp { get; }

Der kleinstgültige Zeitstempel, derzeit immer Anfang des Datums 01.01.1000.

public static DateTime MaxTimestamp { get; }

Der höchstgültige Zeitstempel, derzeit immer eine 'Mikrosekunde vor Ende des Tages 31.12.9999.

public static bool IsMinTimestamp(DateTime value)
public static bool IsMaxTimestamp(DateTime value)
public static bool IsMinOrMaxTimestamp(DateTime value)

Prüfungen zur Feststellung, ob ein bestimmter Zeitsttempel dem kleinstmöglichen, größtmöglichen Zeitstempel oder eines von beiden entspricht.

public static bool IsInRange(DateTime check, DateTime from, DateTime to)
public static bool IsDateInRange(DateTime check, DateTime from, DateTime to)
public bool IsNowInRange(DateTime from, DateTime to)
public bool IsTodayInRange(DateTime from, DateTime to)

Die InRange-Methoden prüfen, ob eine Datum/Uhrzeit oder ein Datum innerhalb vorgegebener Grenzen liegt. Beide Grenzwerte werden inklusive akzeptiert. Die Uhrzeit-Komponente wird bei den Methoden IsTodayInRange und IsDateInRange ignoriert.

public String ToTimestampString(DateTime timestamp)
public static String ToTimestampString(DateTime timestamp)

Die Methode ToTimestampString erwartet ein DateTime als Argument und wandelt diese in einem String nach Timestamp-Konventionen um. Das Format für die Konvertierung ist sinngemäß YYYY-MM-DD-hh.mm.ss.mmmµµµ. Die statische Variante befindet sich in der statischen Klasse TeamWiSE.Runtime.Common.TimestampServices.

public DateTime FromTimestampString(String timestamp)
public static DateTime FromTimestampString(String timestamp)

Die Methode FromTimestampString erwartet ein String in Timestamp-Konventionen als Argument und wandelt diese in einem DateTime um. Wenn das Argument kein gültiges Format aufweist, wird eine ArgumentException aufgeworfen. Die statische Variante befindet sich in der statischen Klasse TeamWiSE.Runtime.Common.TimestampServices.

public DateTime? Parse(String timestamp)
public static DateTime? Parse(String timestamp)

Die Methode Parse erwartet ein String in Timestamp-Konventionen als Argument und wandelt diese in einem nullable DateTime oder DateTime? um. Wenn das Argument kein gültiges Format aufweist, wird null zurück geliefert. Die statische Variante befindet sich in der statischen Klasse TeamWiSE.Runtime.Common.TimestampServices.

public Boolean TryParse(String timestamp, out DateTime result)
public static Boolean TryParse(String timestamp, out DateTime result)

Die Methode TryParse erwartet ein String in Timestamp-Konventionen als Argument und wandelt diese in einem DateTime um. Wenn die Konvertierung nicht möglich ist (bspw. fehlerhaftes Format) wird false geliefert, sonst true. Die statische Variante befindet sich in der statischen Klasse TeamWiSE.Runtime.Common.TimestampServices.

Der Abschnitt Trace bietet diverse Methoden und Eigenschaften zur Unterstützung für Funktionalitäten in Bezug zu Aufzeichnungen. Die Methoden und Eigenschaften werden im Kontext des aktuellen Bausteins ausgeführt.

public Boolean IsActive { get; }

Gibt an, ob für die Aktivitäten in der zugrundeliegenden Ausführung aktuell eine Aufzeichnung konfiguriert und aktiv ist. Normalerweise ist es nicht notwendig, diese Eigenschaft abzufragen, da die Write-Befehle immer ausgeführt werden können und lediglich ins Leere gehen, sollte nicht aufgezeichnet werden. Wenn allerdings die Erstellung der Daten für die Write-Anweisungen aufwendig ist, kann es Sinn machen dies nur im Falle einer aktiven Aufzeichnung zu tun.

public void Write<T>(String name, T value)
public void Write<T>(T value)

Erzeuge einen Namen/Wert-Eintrag in der Aufzeichnung. Diese Informationen können innerhalb der TAA Testumgebung angesehen, analysiert und verglichen werden. Falls für die zugrundeliegende Ausführung aktuell keine Aufzeichnung konfiguriert und aktiv ist, wird die Anweisung ignoriert. Wird kein Name als Argument übergeben, so wird der Wert unter dem Namen festgelegt in DefaultInfoName in die Aufzeichnungsdaten eingetragen.

Folgender Beispielcode führt bspw. zu folgende Eintragung:

this.Services.Trace.Write("lObj.BvgKtoNr", lObj.BvgKtoNr);
this.Services.Trace.Write("#lObj.BvgKtoNr", lObj.BvgKtoNr.GetHashCode());

public static String DefaultInfoName { get; set; }

Falls mit der Write-Anweisung Werte ohne expliziten Namen in die Aufzeichnung eingetragen werden sollen, so werden diese Einträge mit dem Namen dieser Eigenschaft vorgenommen. Der Vorgabewert ist "info".

public String Name { get ; }

Name der Aufzeichnung, unter dem die Aktivitäten in der zugrundeliegenden Ausführung gespeichert werden. Falls keine Aufzeichnung aktiv ist, liefert diese Eigenschaft eine leere Zeichenfolge.

public String Filename { get ; }

Pfadangabe für die Speicherung der Tracedaten. Die Pfadangabe ist im Kontext des Servers, auf dem die Tracedaten gesammelt werden, zu betrachten. Falls keine Aufzeichnung aktiv ist, liefert diese Eigenschaft eine leere Zeichenfolge.

public String Host { get ; }

Name des Servers, auf dem die Tracedaten gesammelt werden. Falls die Tracedaten lokal gesammelt werden, ist diese Angabe ein Punkt (".").

Der Abschnitt Debug bietet Unterstützung beim Debuggen von Modulen.

public void ShowModule()

Zeigt den TemplateDialog für das Modul an, mit den aktuell vorhandenen Schnittstellendaten. Diese können im Template-Dialog auch angepasst werden.

public T Random<T>(T min, T max)

Diese Methode liefert eine Zufallszahl aus dem Bereich min und max. Beim Aufruf kann für die gelieferte Zufallszahl ein numerischer Datentyp angegeben werden. Wenn keine angegeben ist, wird dieser aus den übergebene Datentyp für min und max abgeleitet.