60.3 Service-Modus und Headless-Modus
60.3.1 Übersicht ¶
Für produktive Setups gibt es zwei Betriebsarten ohne UI: den Service-Modus (Windows-Dienst, vom Service Control Manager verwaltet) und den Headless-Modus (Konsolen-Prozess ohne UI-Abhängigkeit). Beide Modi nutzen dasselbe Programm AEPProcessor.exe - der Unterschied liegt in den Kommandozeilen-Parametern.
Die UI (AutomaticEmailProcessor.exe) wird parallel nur noch zur Konfiguration und Überwachung gestartet - sie kommuniziert mit dem laufenden Prozessor über IPC-Dateien, nicht über direkten Funktionsaufruf.
60.3.2 Modi im Vergleich ¶
| Aspekt |
Anwendungs-Modus |
Service-Modus |
Headless-Modus |
| Programm |
AutomaticEmailProcessor.exe |
AEPProcessor.exe --service |
AEPProcessor.exe --headless |
| Sichtbarkeit |
UI-Fenster |
Hintergrund-Dienst, kein UI |
Konsolen-Prozess, kein UI |
| Verwaltung |
Manuell oder Autostart |
Service Control Manager (sc.exe) |
NSSM, Aufgabenplanung, Skripte |
| Anmeldung erforderlich? |
Ja |
Nein |
Hängt vom Aufrufer ab |
| Empfohlen für |
Konfiguration, Test |
Server, Dauerbetrieb |
Geplante Aufgaben, Container |
In den meisten Produktiv-Setups ist der Service-Modus die richtige Wahl. Headless-Modus eignet sich, wenn der Prozessor durch einen externen Prozess-Manager (NSSM, Windows-Aufgabenplanung) gestartet werden soll.
60.3.3 Kommandozeilen-Parameter ¶
AEPProcessor.exe unterstützt folgende Parameter:
| Parameter |
Kurzform |
Beschreibung |
--service |
-s |
Windows-Dienst-Modus (Service Control Manager) |
--headless |
-h |
Konsolen-Modus, autonome Verarbeitung ohne UI |
--run_once |
-r |
Einmal-Verarbeitung, danach beenden |
--quit |
-q |
Signal an alle laufenden Instanzen, sich zu beenden |
--profile <Name> |
-p <Name> |
Auf ein Profil einschränken; mehrfach verwendbar für mehrere Profile |
--profiles [A,B,C] |
-ps [A,B,C] |
Mehrere Profile in einer Klammer-Liste angeben |
--help |
/? |
Kurzhilfe ausgeben |
Beispiele:
AEPProcessor.exe --service
AEPProcessor.exe --headless
AEPProcessor.exe --headless --run_once
AEPProcessor.exe --headless --run_once --profile "Eingangsrechnungen"
AEPProcessor.exe --headless --run_once --profile "Eingangsrechnungen" --profile "Bestellungen"
AEPProcessor.exe --headless --run_once --profiles [Eingangsrechnungen,Bestellungen,Archiv]
AEPProcessor.exe --quit
Profilnamen mit Komma: Innerhalb der Klammer-Liste können einzelne Namen in Anführungszeichen gesetzt werden, wenn sie selbst ein Komma enthalten - sowohl doppelte als auch einfache Anführungszeichen werden unterstützt:
AEPProcessor.exe -h -r --profiles ["Rechnungen, Eingang",Bestellungen,"Archiv, Alt"]
Hinweis: Profilnamen sind nicht case-sensitive. Inaktive oder nicht existierende Profile werden übersprungen. Ohne Profilangabe werden alle aktiven Profile verarbeitet.
60.3.4 Exit-Codes ¶
Der Prozessor beendet sich mit folgenden Exit-Codes - nützlich für Skripte und die Aufgabenplanung:
| Code |
Bedeutung |
| 0 |
Erfolgreich beendet |
| 1 |
Unbehandelte Ausnahme |
| 2 |
Lizenz abgelaufen oder ungültig |
| 3 |
Konfigurations-Fehler (z.B. AppData-Verzeichnis nicht erreichbar) |
| 4 |
Andere Instanz läuft bereits |
60.3.5 Dienst installieren ¶
Mit sc.exe (Standard-Methode)
sc.exe create "AEP4Service" binPath= "C:\Programme\AutomaticEmailProcessor\AEPProcessor.exe --service"
sc.exe config "AEP4Service" obj= ".\ServiceUser" password= "***"
sc.exe config "AEP4Service" start= auto
sc.exe start "AEP4Service"
Mit NSSM (Non-Sucking Service Manager)
NSSM verwaltet den Prozess extern und benötigt daher den Headless-Modus:
nssm install AEP4Service "C:\Programme\AutomaticEmailProcessor\AEPProcessor.exe" --headless
nssm set AEP4Service ObjectName ".\ServiceUser" "***"
nssm start AEP4Service
Dienst-Konto
Wichtig: Der Dienst muss unter einem Windows-Benutzerkonto laufen - typischerweise einem dedizierten Benutzer oder Domain-Account. Das Konto „Lokales System” ist ungeeignet, weil:
- Microsoft 365 OAuth-Tokens an einen Windows-Benutzer gebunden sind - Lokales System hat keinen sinnvollen Token-Cache
- Passwörter im Modus Windows Credential Manager an den Windows-Benutzer gebunden sind - Lokales System kann sie nicht lesen
- Drucker-Berechtigungen pro Benutzer gesetzt sind - Lokales System hat oft keinen Zugriff auf Netzwerk-Drucker
- Die Heartbeat- und IPC-Daten zwischen UI und Dienst in der Benutzer-Registry (
HKEY_CURRENT_USER) liegen - läuft der Dienst unter einem anderen Konto, meldet die UI „Externer Prozessor nicht aktiv”, obwohl der Dienst korrekt arbeitet
Empfehlung: Service-Account-Benutzer einrichten, sich einmalig mit diesem Account anmelden, dort die UI starten und Konten/Lizenz konfigurieren, dann den Dienst auf diesen Account umkonfigurieren.
60.3.6 UI-Option „Externer Prozessor” ¶
Damit die UI dem Dienst nicht ins Gehege kommt, aktivieren Sie in den Programmoptionen → Verarbeitung unter Externer Prozessor das Häkchen „Externen Prozessor verwenden (z.B. Windows-Dienst)“.
Wirkung: Die UI startet, überwacht oder beendet den Prozessor nicht selbst - sie geht davon aus, dass der Dienst eigenständig läuft, und kommuniziert nur über die IPC-Dateien. Ohne diese Option würde die UI bei jedem Start versuchen, einen eigenen Prozessor-Prozess zu starten und beim Beenden wieder zu killen.
60.3.7 Geplante Aufgabe ¶
Für regelmäßige Einmal-Verarbeitungen ohne Dauerbetrieb können Sie eine geplante Aufgabe einrichten. Die Aufgabe ruft AEPProcessor.exe mit --headless --run_once auf, verarbeitet einmalig und beendet sich.
schtasks /create /sc daily /tn "AEP4 Nachtlauf" ^
/tr "\"C:\Programme\AutomaticEmailProcessor\AEPProcessor.exe\" -h -r" ^
/st 02:00
schtasks /create /sc hourly /tn "AEP4 Rechnungen" ^
/tr "\"C:\Programme\AutomaticEmailProcessor\AEPProcessor.exe\" -h -r -p \"Eingangsrechnungen\"" ^
/mo 1
Mit verschiedenen Aufgaben für unterschiedliche Profile lassen sich flexible Verarbeitungszeiten einrichten - z.B. Rechnungen tagsüber stündlich, Archivierung nachts einmal täglich.
60.3.8 Diagnose ¶
Bei Problemen mit dem Dienst hilft die Datei ServiceDiagnostics.log, die im selben Verzeichnis wie AEPProcessor.exe angelegt wird. Sie enthält Startmeldungen, die erkannte Betriebsart und Fehler aus der Initialisierungsphase - oft die einzige Spur, wenn der Dienst sich beim Start sofort wieder beendet.
Die regulären Verarbeitungs- und Fehler-Logs liegen wie im Anwendungs-Modus in der Log-Datenbank im AppData-Ordner.
60.3.9 Anwendungsfall ¶
Produktiv-Setup auf Server-Hardware
Dienst-Account: firma\AEP-Service. Ausführungsmodus: Service. Autostart bei System-Boot. Die UI wird gelegentlich auf einer Workstation gestartet, um Logs zu prüfen - der Dienst läuft ungestört durch.
60.3.10 Tipps ¶
- Verwenden Sie für den Dienst nicht „Lokales System” - Token-Caches, Credential-Manager-Passwörter und der UI-Heartbeat sind alle an einen Windows-Benutzer gebunden
- Im Service-Modus ist die UI-Anzeige der Anwendungsmeldungen (siehe Kapitel 40.21) wirkungslos - verwenden Sie stattdessen die E-Mail-Benachrichtigungen für kritische Hinweise