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
MSIX via App Installer (recommended)
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
- Is the service running? →
services.msc→ "merchantCENTRAL Print Service" must show Running. The service name isMCPrintService(MSIX) orMC.PrintService(ZIP). - Port open? →
netstat -an | findstr 5050→ must show "LISTENING". - Health check →
http://localhost:5050/healthin 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
- Keys identical? → Put the API key on the clipboard with Copy at
http://localhost:5049/configand paste it again in the API Key field on the printer card. - Key configured? → If the configuration UI shows Not configured, Regenerate creates one.
- Does the reverse proxy forward the
X-Api-Keyheader? - With Relay: check the Relay Function Key on the printer card.
Printer not found
- Windows printer: must be visible in the printer management of the service machine.
- Exact name: the Printer Name in BC must match the Windows printer name exactly.
- Check: the configuration UI
http://localhost:5049/configlists all detected printers. - 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:QueueNameof that computer.
ZPL printing failed
- Network: Is the Zebra printer reachable via
ping <ip>? - Allowed target? Address in a private network and port 9100–9103 or 6101? Otherwise extend
Zpl:AllowedNetworksorZpl:AllowedPorts. - Test print: ZPL connection test in the configuration UI.
Agent does not connect (Relay/Poll)
Relay:Enabled=trueand the listen connection string correct?- 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. - Outbound port 443 to
*.servicebus.windows.netallowed,Relay:TransportType=AmqpWebSockets? - 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) |