Zum Inhalt

Print Service – Einrichtung

Schritt-für-Schritt-Anleitung zur Einrichtung des merchantCENTRAL Print Service: von der Lizenz über die Installation des lokalen Druckdienstes und die Anbindung an Business Central bis zum ersten Testdruck.

Architektur in Kürze

Business Central (Cloud) kann lokale Drucker nicht direkt ansprechen. Der MC.PrintService ist eine kleine lokale Anwendung beim Kunden, die Druckaufträge entgegennimmt und an Windows- oder Zebra-Drucker weiterleitet.

┌──────────────────┐   Druckauftrag    ┌──────────────────┐   PDF / ZPL    ┌──────────────┐
│ Business Central │ ────────────────► │  MC.PrintService │ ─────────────► │   Drucker    │
│   (Cloud/SaaS)   │                   │   (beim Kunden)  │                │ Windows/Zebra│
└──────────────────┘                   └──────────────────┘                └──────────────┘

Für den Weg von BC zum MC.PrintService gibt es drei Transportmodi. Sie werden je Drucker gewählt (Feld Transportmodus auf der Druckerkarte) und lassen sich mischen.

Direkt-Push (Standard) Relay (Azure-Queue) Poll (Azure-Queue)
Funktionsweise BC ruft den Dienst direkt über die feste öffentliche Adresse auf BC stellt den Auftrag in eine Queue im Azure des Kunden Die Azure Function holt die Aufträge bei BC ab; BC bleibt passiv
Eingehende Portfreigabe erforderlich nicht erforderlich nicht erforderlich
Feste öffentliche IP erforderlich nicht erforderlich nicht erforderlich
HTTPS-Zertifikat selbst verwalten entfällt entfällt
BC macht ausgehende Aufrufe ja ja (Auftrag inkl. Etikett) nein (nur ein kurzer Wake-Ping)
Azure-Abonnement des Kunden nein ja (wenige Euro/Monat) ja (wenige Euro/Monat)

Welchen Modus wählen?

Direkt-Push ist der Standard und für die meisten Kunden die beste Wahl: keine Zusatzkosten, sofortige Statusrückmeldung, einfach. Voraussetzung sind eine feste öffentliche IP und die Möglichkeit, einen Port freizugeben. Relay und Poll sind für Kunden ohne feste IP bzw. ohne eingehende Portfreigabe. Der Unterschied: Bei Relay stellt BC den Auftrag aktiv in das Azure des Kunden; bei Poll bleibt BC vollständig passiv, die Function holt die Aufträge ab – ideal, wenn BC keine ausgehenden Webdienst-Aufrufe machen soll.

Wo laufen die Druckdaten?

Druckdaten laufen nie über Infrastruktur von ALTENBRAND: bei Direkt-Push direkt von Business Central zum MC.PrintService, bei Relay und Poll über das eigene Azure-Abonnement des Kunden.

Voraussetzungen

  • [ ] merchantCENTRAL Hub – installiert und eingerichtet
  • [ ] Print Service App – installiert (AppSource oder Bereitstellung durch ALTENBRAND)
  • [ ] Modul-Lizenz – mindestens eine Demo-Lizenz für PRINTSERVICE
  • [ ] Windows-Rechner im Kundennetz, der dauerhaft läuft und die Drucker erreicht: Windows 10 ab Version 1903, Windows 11 oder Windows Server 2022 und neuer, mit Administratorrechten für die Installation. Windows Server 2016/2019: nur mit dem ZIP-Paket (Variante B)
  • [ ] Drucker – Windows-Druckertreiber (für PDF) oder Zebra-Drucker per TCP/IP im lokalen Netz erreichbar (für ZPL)
  • [ ] Bei Direkt-Push zusätzlich: feste öffentliche IP und Zugriff auf Router/Firewall
  • [ ] Bei Relay/Poll zusätzlich: ein Azure-Abonnement des Kunden (Details in Teil B)

Schritt 1: Lizenz und Modul aktivieren

Lizenz und Einschalten laufen – wie bei den anderen merchantCENTRAL-Modulen – über die zentrale Hub-Karte Erweiterung des Moduls.

  1. In BC nach merchantCENTRAL-Einrichtung suchen → Bereich Erweiterungen → Zeile Print Service → Aktion Einrichten (ein Klick auf den Namen öffnet dagegen das Dashboard). Es öffnet sich die Hub-Karte Erweiterung; ihr Teil Lizenz zeigt den Lizenzstatus. Auch direkt nach der Installation steht der Print Service dort: Beim Öffnen der merchantCENTRAL-Einrichtung registriert der Hub neu installierte Module.
  2. Demo registrieren (Aktion im Teil Lizenz) schaltet eine Demo-Lizenz frei; Lizenz aktualisieren fragt den Lizenzserver erneut ab. Bei einer Demo zeigt der Teil zusätzlich Demo-Status (verbleibende Tage) und Demo-Ablauf.
  3. In der Gruppe Allgemein derselben Karte den Schalter Aktiviert einschalten. Dabei prüft der Hub die Lizenz und bietet die Demo-Registrierung an.

Ohne eingeschaltetes Modul wird nichts automatisch gedruckt

Lizenz und Einschalten sind zwei Schritte. Solange das Modul nicht eingeschaltet ist, reiht der Print Service weder Versandetiketten noch Berichte aus Buchungen ein. Das Dashboard nennt diesen Grund im Hinweis-Banner.

Einrichtungsassistent

Die unterstützte Einrichtung merchantCENTRAL Druckservice einrichten (unter Unterstützte Einrichtung, auch als Aktion Einrichtungsassistent im Aktionsmenü der Druckservice-Einstellungen) führt durch die folgenden Schritte: Druckdienst herunterladen, ersten Drucker anlegen (mit Verbindungstest bei Direkt-Push) und automatischen Druck einschalten.

Schritt 2: MC.PrintService installieren

Der lokale Druckdienst wird einmalig auf einem Rechner im Kundennetz installiert, der dauerhaft läuft und die Drucker erreicht. Bei Relay und Poll arbeitet dieselbe Installation zusätzlich im Agent-Modus (siehe Teil B).

Variante A – MSIX über den App Installer (empfohlen)

  1. In BC die Druckservice-Einstellungen (Aktionsmenü des Teils, Gruppe Installation) oder eine Druckerkarte öffnen → Aktion Druckdienst herunterladen. Die Downloadseite ist auf die Versionen vorgefiltert, die zu Ihrer Installation passen.
  2. Die Installation über den Windows App Installer starten. Der Windows-Dienst merchantCENTRAL Print Service (Dienstname MCPrintService, Konto LocalSystem, Autostart) wird eingerichtet, gestartet und automatisch aktuell gehalten.
  3. Auf dem Rechner die Konfigurationsoberfläche http://localhost:5049/config öffnen – im Browser oder in BC mit der Aktion Lokale Konfiguration öffnen – und den API-Schlüssel mit Kopieren in die Zwischenablage legen. Angezeigt wird er nie. Er wird beim ersten Start automatisch erzeugt und bei Direkt-Push in BC benötigt.

Die eingehende Firewall-Regel für den Druck-Port legt der Dienst beim ersten Start selbst an.

Variante B – ZIP-Paket mit Install.bat

Sofern Ihnen ALTENBRAND ein ZIP-Paket bereitgestellt hat (auch für Windows Server 2016/2019, auf denen die MSIX-Installation nicht läuft):

  1. ZIP-Paket entpacken.
  2. Install.bat doppelklicken → Benutzerkontensteuerung bestätigen.
  3. Das Skript (install.ps1) richtet den Windows-Dienst merchantCENTRAL Print Service (Dienstname MC.PrintService) mit Autostart und die Firewall-Regel ein. Den API-Schlüssel zeigt es nicht an, sondern legt ihn in die Zwischenablage – fügen Sie ihn in BC ein (A4). Später kopiert ihn die Konfigurationsoberfläche jederzeit wieder mit Kopieren.

Ports und API-Schlüssel

Port Zweck Erreichbar
5050 Druck-API für Business Central aus dem Netz – jeder Aufruf außer /health nur mit API-Schlüssel
5049 Konfigurationsoberfläche http://localhost:5049/config nur lokal auf dem Rechner selbst

Die Konfigurationsoberfläche (im merchantCENTRAL-Layout, auf Deutsch und Englisch) zeigt:

  • den Dienststatus und die Version,
  • ob ein API-Schlüssel eingerichtet ist – den Schlüssel selbst nie. Kopieren legt ihn in die Zwischenablage; Neu erzeugen erzeugt einen neuen, legt ihn ebenfalls in die Zwischenablage und macht den alten sofort ungültig – danach muss er in BC ersetzt werden,
  • den Agent-Modus für Relay/Poll mit der Warteschlange, die der Dienst liest,
  • die installierten Windows-Drucker und einen ZPL-Verbindungstest,
  • Einrichtungshinweise für Business Central.

Ohne API-Schlüssel keine Druck-API

Ohne eingerichteten API-Schlüssel lehnt die Druck-API jede Anfrage außer /health ab – aus Business Central ebenso wie vom Rechner selbst. Neu erzeugen legt einen an. Relay- und Poll-Drucker brauchen den Schlüssel nicht.

Konfigurationsdatei

Einstellungen und API-Schlüssel liegen unter %ProgramData%\merchantCENTRAL\PrintService\appsettings.json (nur für SYSTEM und Administratoren lesbar). Alle Einstellungen: MC.PrintService – Referenz.

Teil A: Direkt-Push einrichten

Beim Direkt-Push erreicht Business Central den MC.PrintService über die feste öffentliche IP des Kunden. Drei Schutzschichten sichern den Zugang ab: API-Schlüssel, HTTPS und eine Firewall-Einschränkung auf Business Central.

A1 – HTTPS bereitstellen

Business Central (Cloud) sendet Druckaufträge aus dem Azure-Rechenzentrum und validiert dabei das Serverzertifikat. Selbstsignierte Zertifikate funktionieren nicht. Wählen Sie eine Option:

Option Beschreibung Geeignet für
Reverse Proxy (empfohlen) Caddy, nginx oder IIS vor dem Dienst, Subdomain je Kunde (z. B. print.kunde.de → feste IP), Let's-Encrypt-Zertifikat automatisch die meisten Kunden mit eigener Domain
Let's-Encrypt-IP-Zertifikat Zertifikat direkt auf die IP-Adresse (kurzlebig, automatische Erneuerung per ACME) Kunden ohne Domain
Kestrel mit PFX HTTPS direkt im Dienst: Kestrel:Endpoints:Https in appsettings.json mit Pfad zum Zertifikat einfache Setups mit vorhandenem Zertifikat

Reverse Proxy mit Caddy

Caddy beschafft und erneuert Let's-Encrypt-Zertifikate vollautomatisch. Eine minimale Caddyfile lautet: print.kunde.de { reverse_proxy localhost:5050 }.

Nur den Druck-Port veröffentlichen

Leiten Sie ausschließlich Port 5050 weiter. Die Konfigurationsoberfläche (Port 5049) darf nie über den Proxy oder die Firewall veröffentlicht werden.

A2 – Port-Forwarding einrichten

Leiten Sie im Router/Firewall den öffentlichen HTTPS-Port (z. B. 443) auf den Rechner mit dem MC.PrintService weiter (Port 5050 bzw. den Port des Reverse Proxy).

A3 – Firewall auf Business Central beschränken

Damit der weitergeleitete Port nicht für das gesamte Internet offen steht, beschränken Sie den eingehenden Zugriff auf die IP-Adressen von Business Central. Diese sind im Azure-Service-Tag Dynamics365BusinessCentral zusammengefasst (von Microsoft automatisch gepflegt).

  • Firewalls mit Service-Tag-Unterstützung verwenden den Tag direkt.
  • Andernfalls die IP-Bereiche als JSON-Liste herunterladen und als Regel hinterlegen.

A4 – Drucker in Business Central anlegen

  1. In BC nach Drucker (Druckservice) suchen → Neu.
  2. Transportmodus auf Direkt-Push belassen.
  3. Felder ausfüllen:
Feld Wert
Code Eindeutige Kennung, z. B. PDF-BÜRO oder ZPL-LAGER1
Beschreibung Sprechender Name
Service-URL Öffentliche HTTPS-URL des Dienstes, z. B. https://print.kunde.de (für lokale Tests http://localhost:5050)
API-Schlüssel Feld anklicken → den in Schritt 2 kopierten API-Schlüssel einfügen (Strg+V). Er wird verschlüsselt gespeichert, das Feld zeigt nur Konfiguriert bzw. Nicht konfiguriert
Druckername Bei PDF: exakter Windows-Druckername. Bei ZPL: IP-Adresse des Zebra-Druckers
Druckmethode PDF (Windows-Drucker) oder ZPL (Zebra-Thermodrucker)
ZPL-Port Nur bei ZPL: TCP-Port (Standard 9100)

HTTPS-Pflicht für entfernte Adressen

Die Service-URL muss https:// verwenden. http:// ist nur für localhost/127.0.0.1 (lokale Tests) zulässig und wird für entfernte Adressen abgewiesen.

A5 – Verbindung testen

Auf der Druckerkarte die Aktion Verbindung testen ausführen. Bei Erfolg wechselt der Status auf Online. Anschließend einen Testdruck auslösen (siehe Druckwarteschlange).

Fehler Ursache Lösung
Status Nicht verbunden Dienst nicht erreichbar Port-Forwarding, Reverse Proxy, Dienststatus prüfen
Status Fehler, HTTP 401 API-Schlüssel fehlt oder ist falsch In der Konfigurationsoberfläche mit Kopieren holen und auf der Druckerkarte im Feld API-Schlüssel neu einfügen
Zertifikatsfehler Ungültiges oder selbstsigniertes Zertifikat Gültiges Zertifikat (Let's Encrypt) verwenden

Teil B: Relay und Poll (Azure)

Bei Relay und Poll betreibt der Kunde die Vermittlungskomponenten in seinem eigenen Azure: eine Azure Function auf dem Flex-Consumption-Plan, einen Service Bus mit der Queue print-jobs (bei mehreren druckenden Rechnern zusätzlich je Rechner eine Queue print-jobs-<agent>, siehe Mehrere Rechner) und einen Storage Account für die Etiketten. Der MC.PrintService läuft im Agent-Modus und hält nur eine ausgehende Verbindung (AMQP über WebSockets, Port 443) – keine Portfreigabe, keine feste IP, kein eigenes Zertifikat.

  • Relay: BC stellt den Auftrag über die Function in die Queue.
  • Poll: Die Function holt die Aufträge bei BC ab – nach einem kurzen Wake-Ping von BC sofort, sonst per Timer (Standard alle 5 Minuten). Ein Poll-Deployment bedient genau eine Company.

In beiden Modi meldet die Function das Druckergebnis an BC zurück; der Auftrag wechselt von Wird gesendet auf Gedruckt bzw. Fehlgeschlagen.

Ablauf in Kürze

  1. Azure-Ressourcen bereitstellen: In den Druckservice-Einstellungen (Aktionsmenü des Teils, Gruppe Installation) die Aktion Relay/Poll in Azure einrichten ausführen. Sie zeigt die Werte für bcCompanyId und bcEnvironmentUrl fertig ausgefüllt an und öffnet das Azure-Portal mit der Vorlage („Deploy to Azure"). Der Function-Code kommt mit der Vorlage. Für Poll den Parameter enablePoll = true setzen, bei mehreren druckenden Rechnern zusätzlich agentNames (siehe Mehrere Rechner).
  2. Business Central freigeben: Das Skript grant-bc-access.ps1 (z. B. in der Azure Cloud Shell) weist der Managed Identity der Function die App-Rolle API.ReadWrite.All von „Dynamics 365 Business Central" zu und gibt deren Client-ID aus. Diese in BC unter Microsoft Entra-Anwendungen eintragen (Status Aktiviert) und den Berechtigungssatz ALN MCPS Relay API (nur Relay) bzw. ALN MCPS Poll API (Poll, deckt Relay mit ab) zuweisen – in jeder Company mit Relay- oder Poll-Druckern. Weitere Berechtigungssätze wie D365 AUTOMATION sind nicht nötig: Beide Sätze schließen D365 Basic - Read ein.
  3. Schlüssel abrufen: Function-Key (Function App → App keys → default) und die Listen-Verbindungszeichenfolge der Queue (print-jobs → Shared access policies → AgentListen). Bei mehreren Rechnern braucht jeder Rechner die Listen-Verbindungszeichenfolge seiner eigenen Queue print-jobs-<agent>.
  4. BC-Seite konfigurieren:
    • Relay: Auf der Druckerkarte Transportmodus = Relay (Azure-Queue), Relay-Function-URL = Basis-URL der Function App, Relay-Function-Key anklicken und den Function-Key eingeben.
    • Poll: Auf der Druckerkarte nur Transportmodus = Poll (Azure-Queue), Druckername und Druckmethode. Die Azure-Anbindung wird einmal zentral in den Druckservice-Einstellungen in der Gruppe Poll-Anbindung (Azure) hinterlegt (Poll-Function-URL, Poll-Function-Key). Dieser Wake-Ping ist im Echtbetrieb Pflicht: Ohne ihn bleibt BC vollständig passiv, und Poll druckt nur im 5-Minuten-Takt des Function-Timers. Mit der Aktion Poll-Anbindung testen prüfen Sie URL und Key; sie zeigt die Antwort der Function.
    • Mehrere Rechner: zusätzlich auf der Druckerkarte das Feld Agent setzen (siehe Mehrere Rechner).
  5. Agent-Modus einschalten: In der appsettings.json des MC.PrintService den Abschnitt Relay befüllen (Enabled, Listen-Verbindungszeichenfolge, Status-URL und Function-Key; bei mehreren Rechnern auch QueueName) und den Dienst neu starten. Siehe MC.PrintService – Referenz.
  6. Testen: Ein Etikett auf den Relay- bzw. Poll-Drucker drucken. Ablauf: Wird gesendet → der Agent druckt → Gedruckt. Bei Poll ohne Wake-Ping kann es bis zum nächsten Timer-Lauf dauern.

Keine Zustimmung erteilen

Auf der Seite Microsoft Entra-Anwendungen die Aktion Zustimmung erteilen nicht ausführen: Eine Managed Identity hat keine App-Registrierung, Entra meldet dort AADSTS1003031. Die Zustimmung hat grant-bc-access.ps1 bereits erteilt – das Skript weist am Ende selbst darauf hin.

Ausführliche Anleitung

Alle Parameter und Ausgaben der Vorlage, Kosten, Updates und die Fehlerbehebung für Relay und Poll beschreibt das Installations- und Benutzerhandbuch des Print Service (Kapitel 7 und 8).

Firewall beim Kunden

Der Agent braucht nur ausgehend Port 443 zu *.servicebus.windows.net. Eine eingehende Portfreigabe ist nicht nötig.

Mehrere Rechner

Ein Rechner im Agent-Modus genügt oft, solange er alle Drucker erreicht: ZPL-Drucker spricht der Dienst über ihre IP-Adresse im Netz an, nur PDF-Drucker müssen auf dem Rechner als Windows-Drucker installiert sein. Drucken mehrere Rechner mit verschiedenen Druckern – z. B. einer im Lager die Etiketten, einer im Büro die Lieferscheine –, bekommt jeder Rechner seine eigene Queue:

  1. Deployment: Im Parameter agentNames die Namen der Rechner angeben, z. B. ["LAGER","BUERO"], und die Vorlage (erneut) in dieselbe Ressourcengruppe deployen. Für jeden Namen entsteht die Queue print-jobs-<name> in Kleinbuchstaben mit eigener Listen-Regel AgentListen. Erlaubt sind Buchstaben, Ziffern und - _ ., höchstens 20 Zeichen.
  2. Jeder Rechner: In der appsettings.json Relay:QueueName = print-jobs-lager und als Relay:ServiceBusConnectionString die Listen-Verbindungszeichenfolge dieser Queue. Status-URL und Function-Key sind für alle Rechner gleich. Die Konfigurationsoberfläche zeigt unter Relay / Poll die Warteschlange an.
  3. Druckerkarte: Feld Agent = LAGER bei allen Druckern, die dieser Rechner druckt (Gruppe Relay (Azure-Queue) bzw. Poll (Azure-Queue)). Drucker ohne Agent laufen über die Standard-Queue print-jobs.

Warum nicht alle Rechner an einer Queue?

Mehrere Agents an derselben Queue teilen sich die Aufträge: Jeder Auftrag geht an den Agent, der ihn zuerst abholt. Fehlt dort der Drucker, schlägt der Auftrag fehl („Printer … is not installed on the print service machine "). Doppelt gedruckt wird nie, aber ein scheinbar zufälliger Teil gar nicht. Gleich eingerichtete Rechner – alle haben alle Drucker – dürfen sich eine Queue teilen.

Agent ohne Queue

Nennt ein Drucker einen Agent, für den das Deployment keine Queue hat, schlägt der Auftrag sofort fehl: „No queue for print agent …". Nach dem Ergänzen von agentNames und erneutem Deployment druckt Wiederholung ihn.

Druckwarteschlange prüfen

Neue Druckaufträge druckt der Print Service sofort: Jeder neue Auftrag – aus einer Buchung, einem Versandetikett, einem Druck von Hand oder einer Wiederholung – startet einen Hintergrund-Task, der ihn Sekunden nach dem Commit erzeugt und sendet, nie in der Buchung selbst. Zusätzlich legt die App einen Aufgabenwarteschlangenposten an, der die Druckwarteschlange alle 5 Minuten ausführt. Er ist das Sicherheitsnetz: Er sendet Wiederholungen nach Ablauf der Wartezeit und übernimmt Aufträge, die ein Task nicht erreicht hat.

Ob er eingeplant ist, zeigt in den Druckservice-Einstellungen das Feld Druckwarteschlange in der Gruppe Wartung (Geplant bzw. Nicht geplant - keine Wiederholungen). Ist er nicht eingeplant, die Aktion Druckwarteschlange neu starten ausführen.

Fehlerbehebung

Eine ausführliche Übersicht finden Sie unter MC.PrintService – Referenz.

Schnellprüfung auf dem Rechner mit dem Druckdienst:

  1. Dienst läuft? → services.msc → „merchantCENTRAL Print Service" muss Wird ausgeführt anzeigen. Der Dienstname (z. B. für Get-Service) ist MCPrintService (MSIX) bzw. MC.PrintService (ZIP).
  2. Erreichbar? → http://localhost:5050/health im Browser (oder in BC die Aktion Lokalen Druckdienst prüfen) → zeigt die Statusseite „Der Druckdienst läuft".
  3. Drucker sichtbar? → http://localhost:5049/config listet die installierten Windows-Drucker.
  4. API-Schlüssel eingerichtet? → Die Konfigurationsoberfläche zeigt oben, ob ein Schlüssel eingerichtet ist (den Schlüssel selbst nie).

Die Aktionen Lokale Konfiguration öffnen und Lokalen Druckdienst prüfen (Druckservice-Einstellungen und Druckerkarte, Gruppe Installation) funktionieren nur auf dem Rechner, auf dem der Dienst installiert ist.

Nächste Schritte