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 |
| 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 on the Print Service Setup page or 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
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: extract it and run Install.bat as
administrator. The script installs the Windows service MC.PrintService to
C:\Program Files\MC.PrintService, sets up automatic start, automatic restart on failure and the
firewall rule, and displays the API key.
→ 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) |
– |
Relay:QueueName |
Name of the queue | 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.
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. It
shows:
- service status and version
- the API key (copy or regenerate)
- whether agent mode (Relay) is active
- the installed Windows printers
- a ZPL connection test
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 |
/ |
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→ "MCPrintService" (MSIX) or "MC.PrintService" (ZIP) must show Running. - Port open? →
netstat -an | findstr 5050→ must show "LISTENING". - Health check →
http://localhost:5050/healthin the browser → returnsHealthy.
HTTP 401 when printing from BC
- Keys identical? → Enter the API key from
http://localhost:5049/configagain in the API Key field on the printer card. - 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.
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?- 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) |