Automatic Email Processor - Online-Hilfe
Umfassende Dokumentation aller Funktionen und Einstellungen

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

Direkt aus dem Programm (ab 4.5.0, empfohlen)

Der einfachste Weg: Aktivieren Sie die Option “Externen Prozessor verwenden” (Abschnitt 60.3.6). Ist noch kein Dienst eingerichtet, bietet das Programm die Einrichtung direkt an - ein kleiner Dialog fragt Dienstname (Vorschlag “AEP4Service”), Dienst-Konto (vorbelegt mit dem angemeldeten Benutzer) und dessen Kennwort ab. Nach einer Administrator-Bestätigung legt das Programm den Dienst an, setzt automatischen Start und Wiederherstellung, vergibt dem Konto das Anmelde-Recht “Als Dienst anmelden” und startet den Dienst. Das Kennwort wird dabei nur an die Windows-Dienstverwaltung übergeben und nicht vom Programm gespeichert.

Erkennt das Programm einen falsch eingerichteten Dienst - der Programmpfad zeigt auf die falsche Programmdatei (typisches Symptom: der Dienststart bleibt hängen bzw. bricht mit Fehler 1053 ab) -, wird die Korrektur ebenfalls direkt angeboten; Dienst-Konto und Kennwort bleiben dabei unverändert. Ein fehlender Parameter --service ist dagegen kein Fehler: Der Prozessor erkennt den Dienststart selbst; der Parameter dient nur der eindeutigen Wiedererkennung in der Dienstverwaltung. Wird versehentlich die AutomaticEmailProcessor.exe (das Hauptfenster) als Dienst registriert, beendet sie sich seit 4.5.0 in einer Dienst-Sitzung sofort mit einem Diagnose-Eintrag, statt unsichtbar weiterzulaufen.

Mit sc.exe (Standard-Methode)

sc.exe create "AEP4Service" binPath= "\"C:\Program Files\Automatic Email Processor 4\AEPProcessor.exe\" --service"
sc.exe config "AEP4Service" obj= ".\ServiceUser" password= "***"
sc.exe config "AEP4Service" start= auto
sc.exe failure "AEP4Service" reset= 86400 actions= restart/60000/restart/60000/restart/60000
sc.exe start "AEP4Service"

Die failure-Zeile setzt die Windows-Wiederherstellung (drei automatische Neustart-Versuche im Minutenabstand, Fehlerzähler-Reset nach 24 Stunden). Damit erholt sich der Dienst selbst, wenn sein erster Start nach einem Server-Neustart fehlschlägt - Details in Abschnitt 60.3.9. Wichtig ist das Leerzeichen nach jedem Gleichheitszeichen (binPath= "..."); außerdem müssen Pfade mit Leerzeichen wie im Beispiel in maskierte Anführungszeichen gesetzt werden - sonst meldet der Dienststart später “Das System kann die angegebene Datei nicht finden”.

Mit NSSM (Non-Sucking Service Manager)

NSSM verwaltet den Prozess extern und benötigt daher den Headless-Modus:

nssm install AEP4Service "C:\Program Files\Automatic Email Processor 4\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 → Windows-Dienst unter Betriebsart das Häkchen “Externen Prozessor verwenden (z.B. Windows-Dienst)” (bis Version 4.4.0 lag die Option auf der Seite “Verarbeitung”).

Die Seite “Windows-Dienst” zeigt darüber hinaus laufend den Zustand des Dienstes: eingerichtet ja/nein, gestartet/angehalten, Starttyp, Dienstkonto und Programmpfad, dazu eine verständliche Gesamtbewertung (z.B. “Der Dienst läuft und verarbeitet” oder “Der Dienst ist falsch eingerichtet”). Alle Verwaltungs-Aktionen sind dort gebündelt: Dienst einrichten, starten, anhalten, korrigieren und entfernen - jede Aktion mit genau einer Administrator-Bestätigung. Beim Entfernen bietet das Programm an, die Option “Externer Prozessor” gleich mit zu deaktivieren, damit die Verarbeitung wieder im Programmfenster läuft. Läuft der Dienst unter einem anderen Benutzerkonto als das Programmfenster, erklärt ein Hinweis auf der Seite, warum kein Lebenszeichen sichtbar ist (IPC-Daten gelten je Benutzerkonto, siehe Abschnitt “Dienst-Konto”).

Programmoptionen, Seite Windows-Dienst: Betriebsart-Option “Externen Prozessor verwenden”, Status-Bereich mit Dienstname, Konto und Programmpfad sowie Aktionen zum Einrichten, Starten, Anhalten und Entfernen des Dienstes

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.

Gut zu wissen: Das Häkchen selbst verarbeitet nichts - es schaltet nur die UI-eigene Verarbeitung ab und überlässt die Arbeit dem Dienst. Damit dabei keine Lücke entsteht, prüft das Programm seit Version 4.0.31 beim Aktivieren der Option (nach dem Bestätigen), ob ein passender Windows-Dienst eingerichtet ist und läuft:

  • Ist ein Dienst vorhanden, aber gestoppt oder nicht auf automatischen Start gesetzt, bietet das Programm an, ihn direkt zu starten und auf Starttyp “Automatisch” zu setzen (dafür ist eine Bestätigung als Administrator nötig). Seit Version 4.2.1 werden dabei auch die Windows-Wiederherstellungsoptionen gesetzt (automatischer Neustart bei Startfehlern, siehe Abschnitt 60.3.9).
  • Ist kein Dienst eingerichtet, bietet das Programm seit Version 4.5.0 die Einrichtung direkt an (siehe Abschnitt 60.3.5); wer lieber manuell einrichtet, erhält weiterhin einen Hinweis samt Anleitungs-Link - das Häkchen allein übernimmt die Verarbeitung nicht.
  • Ist ein Dienst zwar vorhanden, aber falsch eingerichtet (falsche Programmdatei, typischerweise die AutomaticEmailProcessor.exe statt der AEPProcessor.exe), benennt das Programm seit Version 4.5.0 das Problem konkret und bietet die Korrektur direkt an.

Zusätzlich prüft das Programm seit Version 4.2.1 auch beim Programmstart (mit kurzer Anlaufzeit), ob bei aktivierter Option tatsächlich ein Prozessor arbeitet. Läuft der eingerichtete Dienst nicht, wird der Start direkt angeboten bzw. eine Warnung angezeigt - ein stehender Dienst fällt so sofort auf und nicht erst beim Blick auf ausgebliebene Verarbeitungen.

Wenn Sie den Dienst lieber selbst verwalten, sollte er tatsächlich laufen (in services.msc Status “Wird ausgeführt”) und auf Starttyp “Automatisch” stehen - sonst läuft die Verarbeitung nach einem Windows-Neustart nicht mehr an. sc.exe create allein legt den Dienst nur auf “Manuell” an; den Starttyp ändern Sie mit sc.exe config "AEP4Service" start= auto.

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:\Program Files\Automatic Email Processor 4\AEPProcessor.exe\" -h -r" ^
         /st 02:00

schtasks /create /sc hourly /tn "AEP4 Rechnungen" ^
         /tr "\"C:\Program Files\Automatic Email Processor 4\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. Sie wird im AppData-Ordner des Benutzers angelegt, unter dem der Dienst läuft - also %AppData%\Automatic Email Processor 4\ServiceDiagnostics.log dieses Kontos (nicht neben AEPProcessor.exe, da dort unter Program Files kein Schreibzugriff besteht). Sie enthält Startmeldungen, die erkannte Betriebsart (IsWindowsService=True im Dienst-Modus) und Fehler aus der Initialisierungsphase - oft die einzige Spur, wenn der Dienst sich beim Start sofort wieder beendet. Seit Version 4.2.1 protokolliert der Start zusätzlich eine Zeile Profil-Umgebung: ... mit Benutzer, Profilpfad, Sitzungs-Nummer und - falls erkennbar - FSLogix-/UPD-Profilcontainern (siehe Abschnitt 60.3.10).

Die Konfiguration des Dienstes selbst (hinterlegter Programmpfad, Starttyp, Anmeldekonto, Abhängigkeiten) zeigt eine Administrator-Eingabeaufforderung mit einem Einzeiler:

sc.exe qc "AEP4Service"

Die regulären Verarbeitungs- und Fehler-Logs liegen wie im Anwendungs-Modus in der Log-Datenbank im AppData-Ordner.

60.3.9 Dienst-Start nach Server-Neustart

Startet der Server (z.B. nachts) neu, muss der Dienst von selbst wieder anlaufen. Wenn morgens nichts verarbeitet wurde, prüfen Sie in der Windows-Ereignisanzeige (Windows-Protokolle → System) die Einträge rund um die Neustart-Uhrzeit mit der Quelle “Dienststeuerungs-Manager” bzw. dem Dienstnamen. Typische Ursachen und Abhilfen:

  • Starttyp “Manuell”: Der Dienst kommt nach einem Neustart grundsätzlich nicht zurück. Starttyp auf “Automatisch” stellen (siehe Abschnitt 60.3.6 - das Programm bietet das beim Aktivieren des externen Prozessors selbst an).
  • Anmeldefehler des Dienstkontos (Ereignis 7000/7038): Läuft der Dienst unter einem Domänenkonto, kann die Anmeldung beim frühen Start scheitern, weil Netzwerk und Domänencontroller noch nicht erreichbar sind. Abhilfen: die Windows-Wiederherstellungsoptionen des Dienstes auf “Dienst neu starten” stellen (setzt das Programm seit Version 4.2.1 automatisch mit, wenn es den Dienst-Start anbietet), zusätzlich die Gruppenrichtlinie “Beim Start des Computers und bei der Anmeldung immer auf das Netzwerk warten” aktivieren und dem Dienst bei Bedarf Abhängigkeiten mitgeben: sc.exe config "AEP4Service" depend= Netlogon/LanmanWorkstation
  • “Das System kann die angegebene Datei nicht finden” (Ereignis 7000): Der in der Dienstregistrierung hinterlegte Programmpfad stimmt nicht (mehr) - typisch nach einer Neuinstallation in einen anderen Ordner oder wenn beim Anlegen die Anführungszeichen um einen Pfad mit Leerzeichen fehlten. Mit sc.exe qc prüfen (siehe Abschnitt 60.3.8) und den Pfad per sc.exe config "AEP4Service" binPath= "..." korrigieren.

60.3.10 Terminalserver, FSLogix und Benutzerprofil-Container

Auf Terminalservern werden Benutzerprofile oft als Container bereitgestellt (FSLogix Profile Container oder Benutzerprofil-Datenträger/UPD der Remotedesktopdienste). Das verträgt sich nicht ohne Weiteres mit einem Dienst, der unter einem Benutzerkonto läuft:

  • Ein Windows-Dienst unter einem Benutzerkonto hält dessen Profil dauerhaft geladen. Der Profilcontainer bleibt dadurch gesperrt, solange der Dienst läuft.
  • Meldet sich anschließend jemand interaktiv mit demselben Konto an, kann der Container nicht eingehängt werden - Windows erstellt ein temporäres Profil (Benutzerprofildienst-Ereignisse 1511/1515). Persönliche Einstellungen und z.B. das Outlook-Profil samt Datendatei erscheinen dann “verschwunden”.

Empfehlungen für solche Umgebungen:

  • Für den Dienst ein dediziertes Dienstkonto verwenden und dieses Konto in der FSLogix-/UPD-Konfiguration von der Profilverwaltung ausnehmen (klassisches lokales Profil). FSLogix bietet dafür die Gruppe “FSLogix Profile Exclude List”.
  • Mit dem Dienstkonto nicht interaktiv arbeiten (kein Outlook, keine dauerhafte RDP-Sitzung) - nur kurz zur Einrichtung anmelden.
  • Ob der Dienst in einer Container-Umgebung läuft, zeigt die Profil-Umgebung-Zeile in der ServiceDiagnostics.log (siehe Abschnitt 60.3.8).

60.3.11 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.12 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
Nachholverarbeitung Sicherung und Wiederherstellung