MC.PrintService – Referenz & Fehlerbehebung

Der MC.PrintService ist eine lokale .NET-Anwendung (Windows-Dienst oder Docker-Container), die als Brücke zwischen Business Central (Cloud) und den Druckern im Kundennetz fungiert. Sie nimmt Druckaufträge über HTTP(S) entgegen und leitet sie an Windows- oder Zebra-Drucker weiter.

Geführte Einrichtung

Diese Seite ist die technische Referenz. Die vollständige Schritt-für-Schritt-Einrichtung (inkl. Anbindung an Business Central) finden Sie unter Einrichtung.

Systemvoraussetzungen

Windows-Dienst

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 dem konfigurierten Port (Standard: 5050)
Drucker	PDF: Windows-Druckertreiber installiert. ZPL: Zebra-Drucker per TCP/IP erreichbar

Docker-Container

Anforderung	Details
Host	Linux oder Windows mit Docker Engine
Ports	5100 (konfigurierbar)
Druckmethode	Nur ZPL (TCP/IP) out of the box. PDF erfordert einen CUPS-Sidecar

---

Installation

Die empfohlene Installation als Windows-Dienst erfolgt per Doppelklick auf Install.bat. Das Skript registriert den Dienst, richtet Autostart und Firewall-Regel ein und generiert einen API-Key. Manuelle Varianten:

# Build & Veröffentlichung
dotnet publish service/MC.PrintService -c Release -o C:\Services\MC.PrintService

# Als Windows-Dienst registrieren
sc create MC.PrintService binPath="C:\Services\MC.PrintService\MC.PrintService.exe" start=auto
sc start MC.PrintService

→ Geführte Einrichtung inkl. BC-Anbindung: Einrichtung

---

Konfiguration (appsettings.json)

{
  "Logging": {
    "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" }
  },
  "Security": {
    "ApiKey": "<wird bei der Installation generiert>"
  },
  "Kestrel": {
    "Endpoints": {
      "Http": { "Url": "http://0.0.0.0:5050" }
    }
  }
}

Einstellung	Beschreibung	Standard
Security:ApiKey	API-Key für den Remote-Zugriff. Leer = nur lokale Anfragen erlaubt	(generiert)
Kestrel:Endpoints:Http:Url	IP und Port für eingehende Verbindungen	http://0.0.0.0:5050

HTTPS aktivieren

Für den Remote-Betrieb wird HTTPS benötigt. Entweder über einen Reverse Proxy (empfohlen) oder direkt im Dienst über einen zusätzlichen Kestrel:Endpoints:Https-Eintrag mit Zertifikatspfad. Details: Einrichtung.

---

API-Endpunkte

Endpunkt	Methode	Beschreibung
/	GET	Service-Info (Name, Status, Version, ob API-Key gesetzt)
/health	GET	Health-Check (immer offen, für Monitoring)
/version	GET	Versionsinfo + minimale BC-App-Version
/capabilities	GET	Feature-Discovery (PDF/ZPL, MaxCopies)
/printers	GET	Liste der verfügbaren Windows-Drucker
/print/pdf	POST	PDF-Label an Windows-Drucker senden
/print/zpl	POST	ZPL-Label an Zebra-Drucker senden (TCP)
/print/zpl/test	GET	ZPL-Drucker Konnektivitätstest
/config	GET	Konfigurationsoberfläche (Browser)

Zugriffsschutz

Alle Endpunkte außer /health erfordern bei Remote-Zugriff den Header X-Api-Key mit dem konfigurierten Schlüssel. Lokale Anfragen (localhost) sind ohne Key erlaubt – so funktionieren die Konfigurationsoberfläche und lokale Tests ohne weitere Einrichtung.

---

Netzwerk & Firewall

Richtung	Port	Protokoll	Beschreibung
Eingehend	5050 (bzw. 443 via Reverse Proxy)	TCP/HTTPS	Druckaufträge von Business Central
Ausgehend	9100	TCP (Raw)	ZPL-Direktdruck auf Zebra-Drucker
Lokal	—	Windows GDI	PDF-Druck über lokale Druckertreiber

Zugriff auf Business Central beschränken

Beschränken Sie den eingehenden Port per Firewall auf den Azure-Service-Tag Dynamics365BusinessCentral, damit er nicht für das gesamte Internet offen steht.

---

Fehlerbehebung

Dienst nicht erreichbar

1. Läuft der Dienst? → services.msc → „MC.PrintService" muss „Running" sein.
2. Port offen? → netstat -an | findstr 5050 → muss „LISTENING" zeigen.
3. Health-Check → http://localhost:5050/health im Browser → liefert Healthy.

401 Unauthorized bei Druck aus BC

1. API-Key gesetzt? → Konfigurationsoberfläche …/config zeigt den Status oben an.
2. Schlüssel identisch? → Wert in appsettings.json (Security:ApiKey) und in BC am Drucker (Printer Card → API Key) müssen exakt übereinstimmen.
3. Reverse Proxy leitet den Header X-Api-Key durch?

Drucker wird nicht gefunden

1. Windows-Drucker: muss in der Druckerverwaltung des Dienst-Hosts sichtbar sein.
2. Name exakt: Druckername in BC muss exakt dem Windows-Druckernamen entsprechen.
3. Prüfung: http://localhost:5050/printers listet alle erkannten Drucker.

ZPL-Druck fehlgeschlagen

1. Netzwerk: Zebra-Drucker per ping <ip> erreichbar?
2. Port: telnet <ip> 9100 – Verbindung muss aufgebaut werden.
3. Testdruck: http://localhost:5050/print/zpl/test?ip=<ip>&port=9100.

---

Deployment-Modi im Vergleich

Aspekt	Windows-Dienst	Docker	Interaktiv
PDF-Druck	✅ voll	⚠️ nur mit CUPS-Sidecar	✅ voll
ZPL-Druck	✅ TCP/IP	✅ TCP/IP	✅ TCP/IP
Autostart	✅ Windows-Dienst	✅ restart-policy	❌ manuell
Headless	✅	✅	❌ (Tray-Icon)
Empfohlen für	Produktion (PDF + ZPL)	Produktion (ZPL only)	Entwicklung / Tests

Produktionsempfehlung

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