Das Service Framework

Das Service Framework ist ein integraler Bestandteil unserer Software welche als Service in einem System läuft. Dieses Framework kommuniziert mit der jeweiligen Schnittstelle des verwendeten Betriebssystem damit die Software reibungslos läuft. Das Framework bietet auch Funktionen an, mit denen du den Service einfach im System installieren oder deinstallieren kannst.

Die hier beschriebenen funktionen basieren auf unserem Konfigurationssystem. Daher solltest du dieses Kapitel zuerst lesen, falls du das nicht bereits getan hast.

Features

• Stabile und fehlerresistente Basis um Dienste als Service im Betriebssystem zu betreiben.

• Aktionen um den Service via Kommandozeile zu starten und zu stoppen.

• Aktionen um den Service zu installieren und zu deinstallieren.

• Spezieller Trace-Mode mit dem der Service als regulärer Prozess von der Kommandozeile gestartet werden kann.

• Funktion um mehrere instanzen der selben Software unter verschiedenen Namen auszuführen.

Optionen der Kommandozeile

--service-action={action}

Mit dieser Option führst du verschiedene Aktionen aus. Mögliche Bezeichner für die Aktionen sind: start, stop, install und deinstall.

--service-name={name}

Mit dieser Option änderst du den Namen des Services. Verwende diese Option wenn du mehrere Instanzen des Services auf einem System ausführen möchtest.

--service-trace

Mit dieser Option startest du die Software als regulären Prozess von der Kommandozeile. So kannst du einen Service testen, ohne diesen zu installieren oder über den Servicemanager des Betriebssystems starten zu müssen.

Die Option --service-action=

Mit der Option --service-action führst du eine Aktion aus. Dabei wird der Service nicht gestartet, sondern nur die angegebene Aktion ausgeführt.

ExampleService.exe --service-action=install
ExampleService.exe --service-action=stop

Die folgende Tabelle erklärt alle möglichen Aktionen:

Aktion	Beschreibung
start	Die start Aktion startet den installierten Service mit dem Servicemanager des Betriebssystems. Dazu muss der Service installiert sein. Wenn du mehrere instanzen des Services betreibst, kannst du mit der Option --service-name die korrekte Instanz auswählen.
stop	Die stop Aktion stoppt einen installierten Service mit dem Servicemanager des Betriebssystems.
install	Die install Aktion installiert den Service mit dem Servicemanager des Betriebssystems, so dass dieser automatisch mit dem System gestartet wird. Die Aktion verwendet bei der Installation den Absoluten Pfad der ausgeführten Anwendung, daher solltest du sie nur bei einer Anwendung aufrufen welche sich bereits im korrekten Verzeichnis befindet.
uninstall	Die uninstall Aktion entfernt den Service aus dem Servicemanager des Betriebssystems.

Die Option --service-name=

Mit der Option --service-name änderst du den Namen der für die Anwendung als Service verwendet wird. Du brauchst sie nur, wenn du mehrere Instanzen der selben Anwendung als verschiedene Services betreiben möchtest.

Der verwendete Name kann nur Kleinbuchstaben, den Punkt und den Unterstrich enthalten. Die maximale Länge ist 64 Zeichen.

Wenn du einen Service mit einem anderen Namen installierst, wir dieser in Klammern hinter dem Namen der Anwendung angezeigt. Verwendest du jetzt eine der Aktionen, wie start, stop oder uninstall für den Service, musst du diesen Namen angeben.

exmpl.exe --service-action=install --service-name=second
exmpl.exe --service-action=uninstall --service-name=second
exmpl.exe --service-action=start --service-name=second
exmpl.exe --service-action=stop --service-name=second

Wenn du dir die Einträge anschaust, welche mit einem solchen Namen erstellt werden, dann siehst du das die Option --service-name auch bei der Kommandozeile angegeben wird. Das ist notwendig, damit die Anwendung bei der Kommunikation mit dem Servicemanager die korrekte Instanz anspricht.

Die Option --service-trace

Eine Anwendung welche als Service entwickelt wurde kann nicht auf jedem Betriebssystem direkt von der Kommandozeile gestartet werden. Daher existiert die Option --service-trace um solche Anwendungen zu testen.

E:\>ProcessMonitorCollector.exe
Could not start service control dispatcher. You can not run this service from command line.
For testing, use the --service-trace command line option.
Could not start service dispatcher.

Starte den Service von der Kommandozeile

Für schnelle Tests kannst du daher den Service mit der Option --service-trace staten. Dieser startet den Service als regulären Prozess und aktiviert den Trace Modus.

Die Anwendung wird dabei mit den Privilegien des angemeldeten Benutzers gestartet und nicht mit denen welche im Servicemanager eingetragen sind. Falls dies für eine Rolle spielt, musst du dich zuerst mit dem korrekten Benutzer anmelden.

Nach dem Start siehst du auf der Kommandozeile wie der Status zu Running wechselt:

E:\> ExampleService.exe --service-trace
Service changed state into: Starting
Service changed state into: Running

Stoppe einen laufenden Service

Um den Service sicher zu beenden, drücke in dem Konsolenfenster Ctrl+C oder Ctrl+Break. Dies fährt den Service geplant herunter. Sobald dieser den Status Stopped erreicht bist du wieder zurück auf dem Kommandozeilen Prompt.

E:\> ExampleService.exe --service-trace
Service changed state into: Starting
Service changed state into: Running
Received Ctrl+C/Ctrl+Break. User requests stop of service.
Service changed state into: Stopping
Service changed state into: Stopped
Exit service with exit code: 0x00000000
E:\> _

Am Ende siehst du auch den Exitcode der Anwendung. Normalerweise bedeutet der Code Null das die Anwendung erfolgreich beendet wurde.

Fehler Finden

Falls ein Service nicht wie gewünscht funktioniert gibt es verschiedene Wege mehr Informationen über das Problem zu bekommen.

Prüfe Fehler im Windows Event Log

Falls ein Fehler vor dem Start des Services passiert, bevor die Logdatei geschrieben wird, findest du Fehlereinträge im Windows Event Log. Die Einträge sind dort im Abschnitt Application. Hier findest du Probleme mit der Konfiguration, oder wenn es ein Problem mit der Logdatei gibt.

Sieh Dir Fehler in der Konsole an

Ein anderer Weg solch frühe Probleme zu erkennen ist der Start von der Kommandozeile. Fehler welche vor der konfiguration des Log-Systems passieren, werden dabei auf der Kommandozeile ausgegeben.

E:\Demo\> ExampleService.exe --service-trace
Error reading the configuration. The message was: No configuration file found, but a configuration is required for this application. Searched in these directories: E:/Demo/ Accepting the following filenames: ^configuration\.xml$ \.conf_b\.xml$
Exit service with exit code: 0x00000002

Aktiviere Trace Einträge in der Logdatei

Läuft die Anwendung und schreibt eine Logdatei kannst du Trace Logeinträge aktivieren. Entferne dazu den Filter in Konfiguration, damit alle Einträge geschrieben werden.

Das folgende Beispiel zeigt eine minimale Log Konfiguration welche Trace Logeinträge schreibt.

<Module name="Log">
    <List name="FileWriter">
        <ListEntry>
            <Value name="LogFilePath">E:/logs/application.log</Value>
        </ListEntry>
   </List>
</Module>

Verwende unterschiedliche Konfigurationsdateien

Beim Testen gibt es einen einfachen Weg unterschiedliche Konfigurationsdateien zu laden. Wenn du dies mit dem Trace Modus kombinierst, kannst du einfach verschiedene Testumgebungen vorbereiten und diese mit Skripten starten.

Mit der Option --config-file setzt du den Pfad zu der Hauptkonfigurationsdatei.

ExampleService.exe --service-trace --config-file=E:\Test1\configuration.xml

Damit diese Technik funktioniert musst du zuerst alle Konfigurationsdateien aus dem Installationsverzeichnis entfernen, da das Verzeichnis in dem sich die Anwendung befindet immer nach Konfigurationsdateien durchsucht wird.

Du kannst auch mehrere Konfigurationsdateien mit derselben Option angeben:

ExampleService.exe --service-trace
    --config-file=E:\Test1\configuration.xml
    --config-file=E:\Test2\process.conf_b.xml

Es ist auch möglich zusätzliche Verzeichnisse für Konfigurationsdateien anzugeben. Diese Verzeichnisse werden nach Konfigurationsdateien mit der Dateiendung .conf_b.xml durchsucht, oder nach einer Datei configuration.xml. Alle gefundenen Dateien werden beim Start geladen.

ExampleService.exe --service-trace --config-directory=E:\Test3Config

Aktiviere zusätzliche Diagnoseinformationen

Die meisten Anwendungen unterstützen verschiedene Bezeichner um weitere Diagnoseinformationen in die Logdatei zu schreiben. Diese sogenannten Trace Sections sind normalerweise deaktiviert, da sie einen Einfluss auf die Programmleistung haben können und die Logdateien viel grösser werden.

Füge eine EnabledTraceSection Liste der Log-System Konfiguration hinzu, um die Diagnoseinformationen zu aktivieren. Das folgende Beispiel zeigt eine mögliche Konfiguration mit dem Bezeichner HostChanges.

<Module name="Log">
    <List name="FileWriter">
        <ListEntry>
            <Value name="LogFilePath">E:/Logs/Application.log</Value>
        </ListEntry>
    </List>
    <List name="EnabledTraceSections">
        <Value>HostChanges</Value>
    </List>
</Module>

In der Dokumentation unserer Anwendungen findest du teilweise eine Liste von Möglichen Bezeichnern um weitere Diagnoseinformationen zu aktivieren.

Bemerkung

Entferne alle Trace Sections Einträge für ein produktives System, sie können einen negativen Einfluss auf die Leistung haben.