Skip to content

MC.PrintService – Reference & Troubleshooting

MC.PrintService is the local print service of the merchantCENTRAL Print Service: a .NET application that runs as a Windows service on a machine in the customer's network. It receives print jobs from Business Central and forwards them to Windows or Zebra printers. With Relay and Poll, it additionally fetches the jobs from the queue in the customer's Azure in agent mode.

Guided setup

This page is the technical reference. The step-by-step setup (including the connection to Business Central) can be found in Installation.

System Requirements

Requirement Details
Operating system Windows 10 version 1903 or later, Windows 11, or Windows Server 2022 or later (64-bit). The MSIX installation requires Windows build 10.0.18362. Windows Server 2016/2019: ZIP installation only
Runtime No separate installation needed – the .NET runtime is included in the package
Permissions Administrator rights for the installation
Network Direct Push: inbound port 5050 (or reverse proxy). Relay/Poll: outbound port 443
Printers PDF: Windows printer driver installed on this machine. ZPL: Zebra printer reachable via TCP/IP on the local network

Installation

In Business Central, choose the Download Print Service action in the Print Service Settings (action menu of the part, group Installation) or on a Printer Card. The download page shows the versions that match your installation; the installation runs through the Windows App Installer.

  • The service is set up and started as the Windows service merchantCENTRAL Print Service (service name MCPrintService, account LocalSystem, automatic start).
  • Updates are installed automatically via the App Installer.
  • On first start, the service generates an API key and creates the inbound firewall rule for the print port (profiles Domain and Private).

ZIP package with Install.bat

If ALTENBRAND has provided you with a ZIP package (also for Windows Server 2016/2019): extract it and run Install.bat as administrator. The script (install.ps1) installs the Windows service merchantCENTRAL Print Service (service name MC.PrintService) to C:\Program Files\MC.PrintService and sets up automatic start, automatic restart on failure and the firewall rule. It does not show the API key but puts it on the clipboard; later, the configuration UI copies it again at any time.

→ Guided setup incl. BC connection: Installation


Configuration

The settings are stored in %ProgramData%\merchantCENTRAL\PrintService\appsettings.json. The file survives updates, takes precedence over the packaged defaults, and is readable only by SYSTEM and administrators because it contains the API key and the relay credentials.

Setting Description Default
Security:ApiKey API key for the print API (header X-Api-Key). Generated on first start (generated)
Kestrel:Endpoints:Http:Url Print API for Business Central http://0.0.0.0:5050
Kestrel:Endpoints:Admin:Url Configuration UI, local only http://127.0.0.1:5049
Kestrel:Endpoints:Https Optional: HTTPS directly in the service (certificate path and password) –
Relay:Enabled Switch on agent mode for Relay/Poll false
Relay:ServiceBusConnectionString Listen connection string of the queue (AgentListen); with several computers the one of the computer's own queue –
Relay:QueueName Name of the queue. With several printing computers the computer's own queue, print-jobs-<agent> print-jobs
Relay:TransportType AmqpWebSockets (port 443) or AmqpTcp (port 5671) AmqpWebSockets
Relay:MaxDeliveryCount Delivery attempts per message 5
Relay:StatusCallbackUrl / Relay:StatusCallbackKey Status URL of the Function and Function key for reporting back to BC –
Zpl:AllowedNetworks Networks in which ZPL printers may be addressed private networks (see below)
Zpl:AllowedPorts Allowed ZPL printer ports 9100–9103, 6101

Example for agent mode (Relay/Poll):

"Relay": {
  "Enabled": true,
  "ServiceBusConnectionString": "<listen connection string>",
  "QueueName": "print-jobs",
  "TransportType": "AmqpWebSockets",
  "MaxDeliveryCount": 5,
  "StatusCallbackUrl": "<status URL of the Function>",
  "StatusCallbackKey": "<Function key>"
}

Restart the service after a change. The agent runs in addition to the print API – one installation can serve Direct Push and Relay/Poll printers at the same time.

Several computers

When several computers print on different printers, each reads a queue of its own: QueueName then holds print-jobs-<agent> (e.g. print-jobs-lager), and ServiceBusConnectionString the listen connection string of this queue. StatusCallbackUrl and StatusCallbackKey are the same for all computers. On the printer card, the Agent field names the computer. Details: Installation – Several computers.

Enable HTTPS

Direct Push requires HTTPS: either via a reverse proxy (recommended) or directly in the service via Kestrel:Endpoints:Https. Details: Installation.

ZPL print targets

The service only opens TCP connections to printers in private networks (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7) on the printer ports 9100–9103 and 6101. Loopback and link-local addresses are always blocked. If a printer is in another network or on another port, extend Zpl:AllowedNetworks or Zpl:AllowedPorts.

PDF printing

Each page of the PDF is rendered at 300 DPI and placed into the printable area with its aspect ratio intact. If the printer offers a paper size that matches the PDF page, the service picks that size and the matching orientation; otherwise the page is scaled into the printer's default paper. Multiple copies go to the spooler as one print job (at most 99).


Configuration UI

http://localhost:5049/config – reachable only in a browser on the service machine. In Business Central, the Open Local Configuration action (Print Service Settings and printer card, group Installation) opens it there as well. The page in the merchantCENTRAL layout is available in German and English (switch at the top right). It shows:

  • service status, version and the address of the print API
  • whether an API key is configured (Configured or Not configured) – never the key itself. Copy puts it on the clipboard; Regenerate creates a new one and puts it on the clipboard as well. The old key then stops working at once and must be replaced in BC
  • the agent mode Relay / Poll (enabled or disabled) with the queue the service reads
  • the installed Windows printers – enter the printer name in BC exactly as shown
  • a ZPL connection test
  • setup hints for Business Central

Do not publish

The configuration UI must never be made reachable through a reverse proxy or port forwarding. Calling /config on port 5050 redirects a local browser to port 5049; from outside it is not reachable.


API Endpoints (Port 5050)

Endpoint Method Description
/health GET Health check – without API key, for monitoring. A browser on the machine itself gets the status page "The print service is running"; monitoring tools and calls from outside (also through a proxy) get JSON with "status": "Healthy"
/ GET Service info (name, status, version, whether API key and agent mode are configured)
/version GET Version info
/capabilities GET Supported features (PDF, ZPL, copies, paper source, max. copies)
/printers GET List of installed Windows printers
/print/pdf POST PDF to a Windows printer
/print/zpl POST ZPL to a Zebra printer (TCP/IP)
/print/zpl/test GET ZPL connection test (?ip=…&port=9100)

Access protection

All endpoints except /health require the X-Api-Key header with the configured key – also from localhost, because a reverse proxy on the same machine connects from there as well. Without a configured key, all requests except /health are rejected.


Network & Firewall

Direction Port Protocol Description
Inbound 5050 (or 443 via reverse proxy) TCP/HTTPS Print jobs from Business Central (Direct Push only)
Local 5049 HTTP Configuration UI, 127.0.0.1 only
Outbound 443 AMQP over WebSockets Agent mode to *.servicebus.windows.net (Relay/Poll only)
Outbound 9100–9103, 6101 TCP (raw) ZPL direct printing to Zebra printers on the local network
Local – Windows spooler PDF printing via the installed printer drivers

Restrict access to Business Central

Restrict the inbound port via firewall to the Azure service tag Dynamics365BusinessCentral so that it is not open to the entire internet.


Troubleshooting

Service not reachable

  1. Is the service running? → services.msc → "merchantCENTRAL Print Service" must show Running. The service name is MCPrintService (MSIX) or MC.PrintService (ZIP).
  2. Port open? → netstat -an | findstr 5050 → must show "LISTENING".
  3. Health check → http://localhost:5050/health in the browser (or the Check Local Print Service action in BC) → shows the status page "The print service is running". A monitoring tool gets JSON with "status": "Healthy" at the same address.

HTTP 401 when printing from BC

  1. Keys identical? → Put the API key on the clipboard with Copy at http://localhost:5049/config and paste it again in the API Key field on the printer card.
  2. Key configured? → If the configuration UI shows Not configured, Regenerate creates one.
  3. Does the reverse proxy forward the X-Api-Key header?
  4. With Relay: check the Relay Function Key on the printer card.

Printer not found

  1. Windows printer: must be visible in the printer management of the service machine.
  2. Exact name: the Printer Name in BC must match the Windows printer name exactly.
  3. Check: the configuration UI http://localhost:5049/config lists all detected printers.
  4. Right computer? The message "Printer … is not installed on the print service machine " names the computer that received the job. When several computers print via Relay/Poll, the printer's Agent field must match Relay:QueueName of that computer.

ZPL printing failed

  1. Network: Is the Zebra printer reachable via ping <ip>?
  2. Allowed target? Address in a private network and port 9100–9103 or 6101? Otherwise extend Zpl:AllowedNetworks or Zpl:AllowedPorts.
  3. Test print: ZPL connection test in the configuration UI.

Agent does not connect (Relay/Poll)

  1. Relay:Enabled = true and the listen connection string correct?
  2. With several computers: Relay:QueueName = print-jobs-<agent> and the listen connection string of this queue? The key of a queue opens only that one queue.
  3. Outbound port 443 to *.servicebus.windows.net allowed, Relay:TransportType = AmqpWebSockets?
  4. Service restarted after changing the configuration?

Operating Modes

Aspect Windows service (MSIX) Windows service (ZIP) Interactive
PDF printing ✅ ✅ ✅
ZPL printing ✅ ✅ ✅
Auto-start ✅ ✅ ❌ manual
Automatic updates ✅ App Installer ❌ ❌
Recommended for Production Production without App Installer Development / testing (with tray icon)