ECIService – Installation & Konfiguration

Der ECIService ist eine Windows-Anwendung / ein Docker-Container, die als Brücke zwischen Business Central (Cloud) und lokalen Druckern im Netzwerk fungiert. Er empfängt Druckaufträge über HTTP und leitet sie an den konfigurierten Drucker weiter.

Übersicht

┌─────────────────┐        HTTPS        ┌─────────────────┐       Lokal       ┌─────────────────┐
│  Business Central│  ──────────────────► │    ECIService   │  ──────────────► │    Drucker      │
│  (Cloud/SaaS)   │   Print Request      │  (On-Premise)   │   PDF/ZPL        │  (Windows/Zebra)│
└─────────────────┘                      └─────────────────┘                   └─────────────────┘

Systemvoraussetzungen

Windows Service

Anforderung	Details
Betriebssystem	Windows 10/11 oder Windows Server 2016+
Runtime	.NET 10 Runtime (im Installer enthalten)
Speicher	Min. 128 MB RAM
Netzwerk	Eingehende Verbindungen auf konfiguriertem Port (Standard: 5115)
Drucker	Für PDF: Windows-Druckertreiber installiert. Für ZPL: Zebra-Drucker per TCP/IP erreichbar

Docker Container

Anforderung	Details
Host	Linux oder Windows mit Docker Engine
Image	ghcr.io/altenbrand/eciservice:latest
Ports	Port 5115 (konfigurierbar)
Druckmethode	Nur ZPL (TCP/IP) out of the box. PDF mit CUPS-Sidecar möglich

---

Installation

Option A: Windows Service (empfohlen für PDF + ZPL)

1. Installer herunterladen: Von der internen Downloads-Seite oder per Bereitstellung durch ALTENBRAND
2. Installation starten: ECIService-Setup.exe als Administrator ausführen
3. Installationsverzeichnis wählen: Standard: C:\Program Files\ALTENBRAND\ECIService
4. Port konfigurieren: Standard: 5115 (kann bei Konflikten geändert werden)
5. Als Dienst registrieren: Der Installer registriert den ECIService automatisch als Windows-Dienst
6. Dienst starten: Der Dienst startet automatisch (Starttyp: Automatisch)

Option B: Docker Container (empfohlen für ZPL-only)

docker run -d \
  --name eciservice \
  -p 5115:5115 \
  -e ECISERVICE_PORT=5115 \
  --restart unless-stopped \
  ghcr.io/altenbrand/eciservice:latest

Für ZPL-Drucker muss der Container Netzwerkzugriff auf die Zebra-Drucker haben (TCP Port 9100).

Option C: Interaktiver Modus (nur für Entwicklung/Tests)

dotnet ECIService.dll

Startet die Anwendung als Konsolenanwendung mit Tray-Icon. Nützlich für Fehlersuche und Tests.

---

Konfiguration

appsettings.json

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://0.0.0.0:5115"
      }
    }
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  },
  "PrintService": {
    "DefaultZplPort": 9100,
    "PrintTimeout": 30000,
    "HealthCheckInterval": 60
  }
}

Einstellung	Beschreibung	Standard
Kestrel:Endpoints:Http:Url	IP und Port für eingehende Verbindungen	http://0.0.0.0:5115
PrintService:DefaultZplPort	Standard-TCP-Port für ZPL-Drucker	9100
PrintService:PrintTimeout	Timeout in ms für einen einzelnen Druckauftrag	30000
PrintService:HealthCheckInterval	Intervall in Sekunden für Drucker-Health-Checks	60

---

API-Endpunkte

Endpunkt	Methode	Beschreibung
/health	GET	Health-Check (HTTP 200 wenn Service läuft)
/printers	GET	Liste aller verfügbaren Drucker auf dem Host
/capabilities	GET	Feature-Discovery (unterstützte Druckmethoden, Version)
/print/pdf	POST	PDF-Label drucken (Body: JSON mit Base64-PDF + Druckername)
/print/zpl	POST	ZPL-Label drucken (Body: JSON mit Base64-ZPL + Drucker-IP + Port)
/print/zpl/test	GET	ZPL-Drucker Konnektivitätstest

Beispiel: PDF drucken

POST /print/pdf
Content-Type: application/json

{
  "printerName": "HP LaserJet Pro",
  "content": "JVBERi0xLjQK...",
  "copies": 1
}

Beispiel: ZPL drucken

POST /print/zpl
Content-Type: application/json

{
  "printerHost": "192.168.1.50",
  "printerPort": 9100,
  "content": "Xl5YQQpeQ0kxMw..."
}

---

Netzwerk & Firewall

Eingehend (Business Central → ECIService)

Richtung	Port	Protokoll	Beschreibung
Eingehend	5115 (konfigurierbar)	TCP/HTTP	Druckaufträge von BC

Kein HTTPS by Default

Der ECIService lauscht standardmäßig auf HTTP. Für Zugriff aus dem Internet (z. B. bei BC SaaS ohne VPN) sollte ein Reverse Proxy mit TLS-Terminierung (nginx, Caddy, IIS ARR) vorgeschaltet werden.

Ausgehend (ECIService → Drucker)

Richtung	Port	Protokoll	Beschreibung
Ausgehend	9100	TCP (Raw)	ZPL-Direktdruck auf Zebra-Drucker
Lokal	—	Windows GDI	PDF-Druck über lokale Druckertreiber

---

Fehlerbehebung

ECIService nicht erreichbar

1. Dienst läuft? → Windows-Dienste (services.msc) prüfen → „ECIService" muss „Running" sein
2. Port offen? → netstat -an | findstr 5115 → Muss „LISTENING" zeigen
3. Firewall? → Windows-Firewall-Regel für Port 5115 eingehend prüfen
4. Health-Check: → http://<host>:5115/health im Browser öffnen

Drucker wird nicht gefunden

1. Windows-Drucker: Drucker muss in der Windows-Druckerverwaltung des ECIService-Hosts sichtbar sein
2. Name exakt: Druckername in BC muss exakt dem Windows-Druckernamen entsprechen (Groß-/Kleinschreibung)
3. Prüfung: http://<host>:5115/printers zeigt alle verfügbaren Drucker

ZPL-Druck fehlgeschlagen

1. Netzwerk: Zebra-Drucker per ping <ip> erreichbar?
2. Port: telnet <ip> 9100 — Verbindung muss aufgebaut werden
3. Testdruck: http://<host>:5115/print/zpl/test für automatischen Konnektivitätstest

---

Deployment-Optionen im Vergleich

Aspekt	Windows Service	Docker	Interaktiv
PDF-Druck	✅ Volle Unterstützung	⚠️ Nur mit CUPS-Sidecar	✅ Volle Unterstützung
ZPL-Druck	✅ TCP/IP	✅ TCP/IP	✅ TCP/IP
Autostart	✅ Windows-Dienst	✅ restart-policy	❌ Manuell
Headless	✅	✅	❌ (Tray-Icon)
Updates	Installer / MSI	docker pull	Manuell
Empfohlen für	Produktion (PDF + ZPL)	Produktion (ZPL only)	Entwicklung / Tests

Produktionsempfehlung

Für die meisten Kunden ist der Windows Service die beste Wahl: Er unterstützt sowohl PDF- als auch ZPL-Druck und startet automatisch nach Neustarts. Docker ist ideal für reine ZPL-Umgebungen (Lager mit Zebra-Druckern).