Zum Inhalt

MC.PrintService – Referenz & Fehlerbehebung

Der MC.PrintService ist der lokale Druckdienst des merchantCENTRAL Print Service: eine .NET-Anwendung, die als Windows-Dienst auf einem Rechner im Kundennetz läuft. Sie nimmt Druckaufträge von Business Central entgegen und leitet sie an Windows- oder Zebra-Drucker weiter. Bei Relay und Poll holt sie die Aufträge zusätzlich im Agent-Modus aus der Queue im Azure des Kunden.

Geführte Einrichtung

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

Systemvoraussetzungen

Anforderung Details
Betriebssystem Windows 10 ab Version 1903, Windows 11 oder Windows Server 2022 und neuer (64 Bit). Die MSIX-Installation setzt Windows Build 10.0.18362 voraus
Runtime Keine separate Installation nötig – die .NET-Laufzeit ist im Paket enthalten
Rechte Administratorrechte für die Installation
Netzwerk Direkt-Push: eingehend Port 5050 (bzw. Reverse Proxy). Relay/Poll: ausgehend Port 443
Drucker PDF: Windows-Druckertreiber auf diesem Rechner installiert. ZPL: Zebra-Drucker per TCP/IP im lokalen Netz erreichbar

Installation

MSIX über den App Installer (empfohlen)

In Business Central auf der Seite Druckservice Einrichtung oder einer Druckerkarte die Aktion Druckdienst herunterladen wählen. Die Downloadseite zeigt die zu Ihrer Installation passenden Versionen; die Installation läuft über den Windows App Installer.

  • Der Dienst wird als Windows-Dienst MCPrintService (Konto LocalSystem, Autostart) eingerichtet und gestartet.
  • Updates werden über den App Installer automatisch eingespielt.
  • Beim ersten Start erzeugt der Dienst einen API-Schlüssel und legt die eingehende Firewall-Regel für den Druck-Port an (Profile Domäne und Privat).

ZIP-Paket mit Install.bat

Sofern Ihnen ALTENBRAND ein ZIP-Paket bereitgestellt hat: entpacken, Install.bat als Administrator ausführen. Das Skript installiert den Windows-Dienst MC.PrintService nach C:\Program Files\MC.PrintService, richtet Autostart, automatischen Neustart bei Fehlern und die Firewall-Regel ein und zeigt den API-Schlüssel an.

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

Konfiguration

Die Einstellungen liegen in %ProgramData%\merchantCENTRAL\PrintService\appsettings.json. Die Datei überlebt Updates, hat Vorrang vor den mitgelieferten Standardwerten und ist nur für SYSTEM und Administratoren lesbar, weil sie den API-Schlüssel und die Relay-Zugangsdaten enthält.

Einstellung Beschreibung Standard
Security:ApiKey API-Schlüssel für die Druck-API (Header X-Api-Key). Wird beim ersten Start erzeugt (generiert)
Kestrel:Endpoints:Http:Url Druck-API für Business Central http://0.0.0.0:5050
Kestrel:Endpoints:Admin:Url Konfigurationsoberfläche, nur lokal http://127.0.0.1:5049
Kestrel:Endpoints:Https Optional: HTTPS direkt im Dienst (Zertifikatspfad und Passwort) –
Relay:Enabled Agent-Modus für Relay/Poll einschalten false
Relay:ServiceBusConnectionString Listen-Verbindungszeichenfolge der Queue (AgentListen) –
Relay:QueueName Name der Queue print-jobs
Relay:TransportType AmqpWebSockets (Port 443) oder AmqpTcp (Port 5671) AmqpWebSockets
Relay:MaxDeliveryCount Zustellversuche je Nachricht 5
Relay:StatusCallbackUrl / Relay:StatusCallbackKey Status-URL der Function und Function-Key für die Rückmeldung an BC –
Zpl:AllowedNetworks Netze, in denen ZPL-Drucker angesprochen werden dürfen private Netze (siehe unten)
Zpl:AllowedPorts Erlaubte ZPL-Druckerports 9100–9103, 6101

Beispiel für den Agent-Modus (Relay/Poll):

"Relay": {
  "Enabled": true,
  "ServiceBusConnectionString": "<Listen-Verbindungszeichenfolge>",
  "QueueName": "print-jobs",
  "TransportType": "AmqpWebSockets",
  "MaxDeliveryCount": 5,
  "StatusCallbackUrl": "<Status-URL der Function>",
  "StatusCallbackKey": "<Function-Key>"
}

Nach einer Änderung den Dienst neu starten. Der Agent läuft zusätzlich zur Druck-API – eine Installation kann Direkt-Push- und Relay-/Poll-Drucker gleichzeitig bedienen.

HTTPS aktivieren

Für Direkt-Push wird HTTPS benötigt: entweder über einen Reverse Proxy (empfohlen) oder direkt im Dienst über Kestrel:Endpoints:Https. Details: Einrichtung.

ZPL-Druckziele

Der Dienst öffnet TCP-Verbindungen nur zu Druckern in privaten Netzen (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7) auf den Druckerports 9100–9103 und 6101. Loopback- und Link-Local-Adressen sind immer gesperrt. Liegt ein Drucker in einem anderen Netz oder auf einem anderen Port, ergänzen Sie Zpl:AllowedNetworks bzw. Zpl:AllowedPorts.

PDF-Druck

Jede Seite des PDF wird mit 300 DPI gerendert und mit unverändertem Seitenverhältnis in den bedruckbaren Bereich gesetzt. Bietet der Drucker ein Papierformat, das zur PDF-Seite passt, wählt der Dienst dieses Format und die passende Ausrichtung; sonst wird die Seite in das Standardpapier des Druckers skaliert. Mehrere Kopien gehen als ein Druckauftrag an den Spooler (höchstens 99).

Konfigurationsoberfläche

http://localhost:5049/config – nur im Browser auf dem Rechner des Dienstes erreichbar. Sie zeigt:

  • Dienststatus und Version
  • den API-Schlüssel (kopieren oder neu erzeugen)
  • ob der Agent-Modus (Relay) aktiv ist
  • die installierten Windows-Drucker
  • einen ZPL-Verbindungstest

Nicht veröffentlichen

Die Konfigurationsoberfläche darf nie über einen Reverse Proxy oder eine Portfreigabe erreichbar gemacht werden. Ein Aufruf von /config auf Port 5050 leitet einen lokalen Browser auf Port 5049 um; von außen ist sie nicht erreichbar.

API-Endpunkte (Port 5050)

Endpunkt Methode Beschreibung
/health GET Health-Check – ohne API-Schlüssel, für Monitoring
/ GET Service-Info (Name, Status, Version, API-Schlüssel und Agent-Modus konfiguriert)
/version GET Versionsinfo
/capabilities GET Unterstützte Funktionen (PDF, ZPL, Kopien, Papierschacht, max. Kopien)
/printers GET Liste der installierten Windows-Drucker
/print/pdf POST PDF an einen Windows-Drucker
/print/zpl POST ZPL an einen Zebra-Drucker (TCP/IP)
/print/zpl/test GET ZPL-Verbindungstest (?ip=…&port=9100)

Zugriffsschutz

Alle Endpunkte außer /health verlangen den Header X-Api-Key mit dem konfigurierten Schlüssel – auch von localhost, denn ein Reverse Proxy auf demselben Rechner verbindet sich ebenfalls von dort. Ohne konfigurierten Schlüssel werden alle Anfragen außer /health abgelehnt.

Netzwerk & Firewall

Richtung Port Protokoll Beschreibung
Eingehend 5050 (bzw. 443 über Reverse Proxy) TCP/HTTPS Druckaufträge von Business Central (nur Direkt-Push)
Lokal 5049 HTTP Konfigurationsoberfläche, nur 127.0.0.1
Ausgehend 443 AMQP über WebSockets Agent-Modus zu *.servicebus.windows.net (nur Relay/Poll)
Ausgehend 9100–9103, 6101 TCP (Raw) ZPL-Direktdruck auf Zebra-Drucker im lokalen Netz
Lokal – Windows-Spooler PDF-Druck über die installierten 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 → „MCPrintService" (MSIX) bzw. „MC.PrintService" (ZIP) muss Wird ausgeführt anzeigen.
  2. Port offen? → netstat -an | findstr 5050 → muss „ABHÖREN" bzw. „LISTENING" zeigen.
  3. Health-Check → http://localhost:5050/health im Browser → liefert Healthy.

HTTP 401 bei Druck aus BC

  1. Schlüssel identisch? → Den API-Schlüssel aus http://localhost:5049/config auf der Druckerkarte im Feld API-Schlüssel neu eingeben.
  2. Reverse Proxy leitet den Header X-Api-Key weiter?
  3. Bei Relay: Relay-Function-Key auf der Druckerkarte prüfen.

Drucker wird nicht gefunden

  1. Windows-Drucker: muss in der Druckerverwaltung des Dienst-Rechners sichtbar sein.
  2. Name exakt: Der Druckername in BC muss exakt dem Windows-Druckernamen entsprechen.
  3. Prüfung: Die Konfigurationsoberfläche http://localhost:5049/config listet alle erkannten Drucker.

ZPL-Druck fehlgeschlagen

  1. Netzwerk: Zebra-Drucker per ping <ip> erreichbar?
  2. Erlaubtes Ziel? Adresse in einem privaten Netz und Port 9100–9103 oder 6101? Sonst Zpl:AllowedNetworks bzw. Zpl:AllowedPorts ergänzen.
  3. Testdruck: ZPL-Verbindungstest in der Konfigurationsoberfläche.

Agent verbindet sich nicht (Relay/Poll)

  1. Relay:Enabled = true und Listen-Verbindungszeichenfolge korrekt?
  2. Ausgehend Port 443 zu *.servicebus.windows.net freigegeben, Relay:TransportType = AmqpWebSockets?
  3. Dienst nach Änderungen an der Konfiguration neu gestartet?

Betriebsarten

Aspekt Windows-Dienst (MSIX) Windows-Dienst (ZIP) Interaktiv
PDF-Druck ✅ ✅ ✅
ZPL-Druck ✅ ✅ ✅
Autostart ✅ ✅ ❌ manuell
Automatische Updates ✅ App Installer ❌ ❌
Empfohlen für Produktion Produktion ohne App Installer Entwicklung / Tests (mit Tray-Symbol)