Skip to content

MC.PrintService – Reference & Troubleshooting

The MC.PrintService is a local .NET application (Windows service or Docker container) that acts as a bridge between Business Central (Cloud) and the printers on the customer's network. It receives print jobs via HTTP(S) and forwards them to Windows or Zebra printers.

Guided Setup

This page is the technical reference. For the complete step-by-step setup (including integration with Business Central), see Installation.

System Requirements

Windows Service

Requirement Details
Operating System Windows 10/11 or Windows Server 2016+
Runtime .NET 10 Runtime (included in the installer)
Memory Min. 128 MB RAM
Network Incoming connections on the configured port (default: 5050)
Printers PDF: Windows print driver installed. ZPL: Zebra printer reachable via TCP/IP

Docker Container

Requirement Details
Host Linux or Windows with Docker Engine
Ports 5100 (configurable)
Print Method ZPL only (TCP/IP) out of the box. PDF requires a CUPS sidecar

Installation

The recommended installation as a Windows service is done by double-clicking Install.bat. The script registers the service, configures autostart and a firewall rule, and generates an API key. Manual alternatives:

# Build & publish
dotnet publish service/MC.PrintService -c Release -o C:\Services\MC.PrintService

# Register as a Windows service
sc create MC.PrintService binPath="C:\Services\MC.PrintService\MC.PrintService.exe" start=auto
sc start MC.PrintService

→ Guided setup including BC integration: Installation

Configuration (appsettings.json)

{
  "Logging": {
    "LogLevel": { "Default": "Information", "Microsoft.AspNetCore": "Warning" }
  },
  "Security": {
    "ApiKey": "<generated during installation>"
  },
  "Kestrel": {
    "Endpoints": {
      "Http": { "Url": "http://0.0.0.0:5050" }
    }
  }
}
Setting Description Default
Security:ApiKey API key for remote access. Empty = only local requests allowed (generated)
Kestrel:Endpoints:Http:Url IP and port for incoming connections http://0.0.0.0:5050

Enabling HTTPS

HTTPS is required for remote operation. Either via a reverse proxy (recommended) or directly in the service via an additional Kestrel:Endpoints:Https entry with a certificate path. Details: Installation.

API Endpoints

Endpoint Method Description
/ GET Service info (name, status, version, whether an API key is set)
/health GET Health check (always open, for monitoring)
/version GET Version info + minimum required BC app version
/capabilities GET Feature discovery (PDF/ZPL, MaxCopies)
/printers GET List of available Windows printers
/print/pdf POST Send a PDF label to a Windows printer
/print/zpl POST Send a ZPL label to a Zebra printer (TCP)
/print/zpl/test GET ZPL printer connectivity test
/config GET Configuration UI (browser)

Access Protection

All endpoints except /health require the X-Api-Key header with the configured key for remote access. Local requests (localhost) are allowed without a key — this allows the configuration UI and local tests to work without any additional setup.

Network & Firewall

Direction Port Protocol Description
Inbound 5050 (or 443 via reverse proxy) TCP/HTTPS Print jobs from Business Central
Outbound 9100 TCP (Raw) ZPL direct print to Zebra printer
Local — Windows GDI PDF print via local print drivers

Restrict Access to Business Central

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

Troubleshooting

Service Not Reachable

  1. Is the service running? → services.msc → "MC.PrintService" must show "Running".
  2. Port open? → netstat -an | findstr 5050 → must show "LISTENING".
  3. Health check → http://localhost:5050/health in the browser → returns Healthy.

401 Unauthorized When Printing from BC

  1. API key set? → The configuration UI at …/config shows the status at the top.
  2. Keys identical? → The value in appsettings.json (Security:ApiKey) and in BC on the printer (Printer Card → API Key) must match exactly.
  3. Reverse proxy forwarding the X-Api-Key header?

Printer Not Found

  1. Windows printer: must be visible in the print management of the service host.
  2. Exact name: The printer name in BC must exactly match the Windows printer name.
  3. Verification: http://localhost:5050/printers lists all detected printers.

ZPL Print Failed

  1. Network: Zebra printer reachable via ping <ip>?
  2. Port: telnet <ip> 9100 — connection must be established.
  3. Test print: http://localhost:5050/print/zpl/test?ip=<ip>&port=9100.

Deployment Modes Comparison

Aspect Windows Service Docker Interactive
PDF Print ✅ Full ⚠️ Only with CUPS sidecar ✅ Full
ZPL Print ✅ TCP/IP ✅ TCP/IP ✅ TCP/IP
Autostart ✅ Windows Service ✅ restart-policy ❌ Manual
Headless ✅ ✅ ❌ (Tray icon)
Recommended for Production (PDF + ZPL) Production (ZPL only) Development / Testing

Production Recommendation

For most customers, the Windows Service is the best choice: it supports both PDF and ZPL and starts automatically after reboots. Docker is ideal for pure ZPL environments (warehouses with Zebra printers).