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. Windows Server 2016/2019: nur die ZIP-Installation |
| 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 in den Druckservice-Einstellungen (Aktionsmenü des Teils, Gruppe Installation) oder auf 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 merchantCENTRAL Print Service (Dienstname
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 (auch für Windows Server 2016/2019):
entpacken, Install.bat als Administrator ausführen. Das Skript (install.ps1) installiert den
Windows-Dienst merchantCENTRAL Print Service (Dienstname MC.PrintService) nach
C:\Program Files\MC.PrintService, richtet Autostart, automatischen Neustart bei Fehlern und die
Firewall-Regel ein. Den API-Schlüssel zeigt es nicht an, sondern legt ihn in die Zwischenablage;
später kopiert ihn die Konfigurationsoberfläche jederzeit wieder.
→ 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); bei mehreren Rechnern die der eigenen Queue |
– |
Relay:QueueName |
Name der Queue. Bei mehreren druckenden Rechnern die eigene Queue des Rechners, print-jobs-<agent> |
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.
Mehrere Rechner
Drucken mehrere Rechner mit verschiedenen Druckern, liest jeder seine eigene Queue: In
QueueName steht dann print-jobs-<agent> (z. B. print-jobs-lager), in
ServiceBusConnectionString die Listen-Verbindungszeichenfolge dieser Queue.
StatusCallbackUrl und StatusCallbackKey sind für alle Rechner gleich. Auf der Druckerkarte
nennt das Feld Agent den Rechner. Details:
Einrichtung – Mehrere Rechner.
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. In
Business Central öffnet sie dort auch die Aktion Lokale Konfiguration öffnen
(Druckservice-Einstellungen und Druckerkarte, Gruppe Installation). Die Seite im
merchantCENTRAL-Layout gibt es auf Deutsch und Englisch (Umschalter oben rechts). Sie zeigt:
- Dienststatus, Version und die Adresse der Druck-API
- ob ein API-Schlüssel eingerichtet ist (Eingerichtet bzw. Nicht eingerichtet) – den Schlüssel selbst nie. Kopieren legt ihn in die Zwischenablage; Neu erzeugen erzeugt einen neuen und legt ihn ebenfalls in die Zwischenablage. Der alte gilt dann sofort nicht mehr und muss in BC ersetzt werden
- den Agent-Modus Relay / Poll (eingeschaltet oder ausgeschaltet) mit der Warteschlange, die der Dienst liest
- die installierten Windows-Drucker – als Druckername genau so in BC eintragen
- einen ZPL-Verbindungstest
- Einrichtungshinweise für Business Central
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. Ein Browser auf dem Rechner selbst bekommt die Statusseite „Der Druckdienst läuft", Überwachungswerkzeuge und Aufrufe von außen (auch über einen Proxy) bekommen JSON mit "status": "Healthy" |
/ |
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
- Läuft der Dienst? →
services.msc→ „merchantCENTRAL Print Service" muss Wird ausgeführt anzeigen. Der Dienstname istMCPrintService(MSIX) bzw.MC.PrintService(ZIP). - Port offen? →
netstat -an | findstr 5050→ muss „ABHÖREN" bzw. „LISTENING" zeigen. - Health-Check →
http://localhost:5050/healthim Browser (oder in BC die Aktion Lokalen Druckdienst prüfen) → zeigt die Statusseite „Der Druckdienst läuft". Ein Überwachungswerkzeug bekommt unter derselben Adresse JSON mit"status": "Healthy".
HTTP 401 bei Druck aus BC
- Schlüssel identisch? → In
http://localhost:5049/configden API-Schlüssel mit Kopieren in die Zwischenablage legen und auf der Druckerkarte im Feld API-Schlüssel neu einfügen. - Schlüssel eingerichtet? → Zeigt die Konfigurationsoberfläche Nicht eingerichtet, legt Neu erzeugen einen an.
- Reverse Proxy leitet den Header
X-Api-Keyweiter? - Bei Relay: Relay-Function-Key auf der Druckerkarte prüfen.
Drucker wird nicht gefunden
- Windows-Drucker: muss in der Druckerverwaltung des Dienst-Rechners sichtbar sein.
- Name exakt: Der Druckername in BC muss exakt dem Windows-Druckernamen entsprechen.
- Prüfung: Die Konfigurationsoberfläche
http://localhost:5049/configlistet alle erkannten Drucker. - Richtiger Rechner? Die Meldung „Printer … is not installed on the print service machine
" nennt den Rechner, der den Auftrag bekam. Drucken mehrere Rechner über Relay/Poll, muss das Feld Agent des Druckers zu Relay:QueueNamedieses Rechners passen.
ZPL-Druck fehlgeschlagen
- Netzwerk: Zebra-Drucker per
ping <ip>erreichbar? - Erlaubtes Ziel? Adresse in einem privaten Netz und Port 9100–9103 oder 6101? Sonst
Zpl:AllowedNetworksbzw.Zpl:AllowedPortsergänzen. - Testdruck: ZPL-Verbindungstest in der Konfigurationsoberfläche.
Agent verbindet sich nicht (Relay/Poll)
Relay:Enabled=trueund Listen-Verbindungszeichenfolge korrekt?- Bei mehreren Rechnern:
Relay:QueueName=print-jobs-<agent>und die Listen-Verbindungszeichenfolge dieser Queue? Der Schlüssel einer Queue öffnet nur diese eine Queue. - Ausgehend Port 443 zu
*.servicebus.windows.netfreigegeben,Relay:TransportType=AmqpWebSockets? - 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) |