# CoolPrintService **Repository Path**: afeng124/CoolPrintService ## Basic Information - **Project Name**: CoolPrintService - **Description**: ZPL打印网关CoolPrintService,省时高效,值得信奈。 - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 1 - **Created**: 2026-07-12 - **Last Updated**: 2026-11-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # CoolPrint Service · ZPL 标签打印网关 CoolPrint Service 是一个运行在 Windows 上的 ZPL 标签打印网关。它同时提供 **TCP 9100 打印入口**、**本地 HTTP API** 和 **可视化管理台**,接收 ZPL 指令后按配置转发到 **Windows 打印驱动** 或 **串口** 输出,并支持本地渲染预览,方便联调时不浪费标签纸。 > 部署、升级、运维与故障排查请参阅 [部署文档](docs/部署文档.md);接口字段、错误码与调用示例见 [API 接口文档](docs/API接口文档.md)。 ## 界面截图 WinForms 管理端(打印通道、串口参数、服务端口与运行日志): ![WinForms 管理端](docs/images/winform.png) Web 管理台(ZPL 编辑器、服务配置、标签预览、运行状态、接入演示): ![Web 管理台](docs/images/console.png) 本地渲染的示例标签(外框 + Code 128 条码 + RoHS2.0 标识 + 二维码): ![标签预览](docs/images/label-preview.png) ## 功能特性 - **TCP 9100 接入**:监听 `0.0.0.0:9100`,接收外部系统发送的 ZPL 原文,按 `^XZ` 分帧,每帧打印一次。 - **HTTP API**:状态查询、配置读写、打印机枚举、ZPL 预览、直接打印。 - **本地渲染预览**:基于 BinaryKits.Zpl.Viewer + SkiaSharp,支持 `^GE` 椭圆、`^BQ` 二维码、中文 `^CI28`,预览不触发打印。 - **两种打印通道**:Windows 打印驱动(默认,走 winspool RAW)与串口,可在配置中切换。 - **配置持久化**:配置保存在程序目录的 `config.json`,支持部分字段更新;TCP 端口保存后立即生效,API 端口修改后需重启程序。 - **WinForms 管理端 + Web 管理台**:桌面端提供日志与启停控制,浏览器访问 `http://127.0.0.1:5990/` 即可管理。 - **Swagger 在线文档**:`http://127.0.0.1:5990/swagger`。 - **多端接入演示**:内置 WinForm、Web、移动端 H5、Android 四个演示页面,直接展示对应调用代码。 - **服务地址自动识别**:配置默认 `127.0.0.1`;检测到物理网卡时,对外展示地址自动使用网卡 IPv4,也可填写固定 IP 覆盖。 ## 系统要求 - Windows 7 SP1 及以上 - .NET Framework 4.7.2 - 真实出纸需要一个可用的 ZPL 打印机(USB/网口驱动或串口连接) ## 快速开始 1. 使用 Visual Studio 2019 及以上打开 `CoolPrintService.sln`。 2. 还原 NuGet 包后编译 `ZplPrintService` 项目(Release)。 3. 运行 `ZplPrintService.exe`。默认启动 TCP 9100 与 HTTP API 5990。 4. 浏览器打开 `http://127.0.0.1:5990/` 进入管理台。 5. 在“服务配置”中选择打印通道与打印机,保存后按提示重启(如修改了 API 端口)。 命令行构建示例: ```powershell msbuild ZplPrintService\ZplPrintService.csproj /p:Configuration=Release ``` ## 打印通道说明 | 配置值 | 模式 | 说明 | | --- | --- | --- | | `WindowsPrinter`(0,默认) | Windows 打印驱动 | 通过 winspool 以 RAW 方式把 ZPL 投递到已安装的打印机,适用于 USB/网口驱动安装的 ZPL 打印机 | | `SerialPort`(1) | 串口 | 通过 `System.IO.Ports` 直接写入串口,适用于 RS-232/RS-485 连接的打印机 | > TCP 9100 是外部系统**访问本服务**的入口,不是一种打印方式。 ## 配置说明 配置位于程序目录 `config.json`,字段含义: | 字段 | 默认值 | 说明 | | --- | --- | --- | | `TcpPort` | `9100` | ZPL 入站监听端口,保存后立即热切换 | | `ApiPort` | `5990` | HTTP API / 管理台端口,修改后需重启 | | `ConnectionType` | `0` | 打印通道:`0` Windows 驱动,`1` 串口 | | `PrinterName` | 空 | Windows 驱动模式下的打印机名称 | | `HostIp` | `127.0.0.1` | 对外展示地址。保持 `127.0.0.1` 时自动使用本机网卡 IP;填写固定 IPv4 则直接使用 | | `Serial.PortName` | `COM1` | 串口名 | | `Serial.BaudRate` | `9600` | 波特率 | | `Serial.DataBits` | `8` | 数据位(5-8) | | `Serial.Parity` | `0` | 校验位:`None` / `Odd` / `Even` / `Mark` / `Space` | | `Serial.StopBits` | `1` | 停止位:`One` / `OnePointFive` / `Two` | | `Serial.Handshake` | `0` | 流控:`None` / `XOnXOff` / `RequestToSend` / `RequestToSendXOnXOff` | | `PreviewWidthMm` | `100` | 预览宽度(毫米) | | `PreviewHeightMm` | `80` | 预览高度(毫米) | | `PreviewDpmm` | `8` | 预览分辨率(点/毫米) | 关于服务地址: - `HostIp` 只影响**对外展示地址**和演示页中显示的 TCP 地址,不改变 API 的监听地址。 - HTTP API 固定绑定 `127.0.0.1`(非管理员进程无法绑定 `0.0.0.0`),管理台请在服务所在机器上访问。 - TCP 打印端口监听全部网卡,局域网内其他设备可直接连接。 ## HTTP API | 方法 | 路径 | 说明 | | --- | --- | --- | | GET | `/api/status` | 返回 TCP 运行状态、端口、打印通道、打印机、对外地址与本机网卡 IP | | GET | `/api/config` | 读取当前完整配置 | | POST | `/api/config` | 部分更新配置,返回 `apiPortRestartRequired`、`connectionChanged` | | GET | `/api/config/printers` | 枚举本机已安装打印机 | | POST | `/api/preview` | 渲染预览。`text/plain` 传 ZPL 原文,尺寸取配置,返回 `image/png` | | POST | `/api/print` | 直接打印,`text/plain` 传 ZPL 原文 | 示例: ```powershell # 查看运行状态 Invoke-RestMethod http://127.0.0.1:5990/api/status # 预览 ZPL $zpl = "^XA^CI28^FO50,50^A0N,50,50^FDHello^FS^XZ" Invoke-WebRequest -Uri http://127.0.0.1:5990/api/preview -Method Post ` -ContentType text/plain -Body $zpl -OutFile preview.png # 直接打印 Invoke-WebRequest -Uri http://127.0.0.1:5990/api/print -Method Post ` -ContentType text/plain -Body $zpl ``` ## TCP 9100 接入 外部系统把 ZPL 原文写入 TCP 9100 端口即可打印,服务按 `^XZ` 分帧: ```powershell $zpl = "^XA^CI28^FO50,50^A0N,50,50^FDHello^FS^XZ" $client = New-Object System.Net.Sockets.TcpClient("127.0.0.1", 9100) $stream = $client.GetStream() $bytes = [System.Text.Encoding]::UTF8.GetBytes($zpl) $stream.Write($bytes, 0, $bytes.Length) $stream.Flush() $client.Close() ``` ## 接入演示 服务启动后可访问以下页面,按客户端类型展示完整调用示例: - `/demo/winform` — WinForm 调用演示(TCP 9100 与 HTTP API 两种方式) - `/demo/web` — Web 演示(浏览器 / Node.js 两种方式) - `/demo/mobile` — 移动端 H5 演示(移动浏览器联网直接打印) - `/demo/android` — Android 使用演示(HttpURLConnection / Socket 接入) ## 项目结构 ``` coolprintservice_src/ ├─ CoolPrintService.sln ├─ README.md ├─ docs/ # 部署文档、API 文档与界面截图 └─ ZplPrintService/ ├─ Program.cs # 程序入口 ├─ config.json # 默认配置 ├─ WebPage.html # 内嵌 Web 管理台 ├─ Controllers/ # Home / Status / Config / Preview / Print / Demo ├─ DemoPages/ # 四端接入演示页与公共资源 ├─ Forms/ # WinForms 主窗与设计器 ├─ Models/ # ServiceConfig、SerialPortSettings、PrintConnectionType ├─ Services/ # OWIN、TCP、打印、渲染、配置、网络与日志 └─ Properties/ ``` ## 常见问题 - **TCP 端口启动失败**:端口被占用,修改 `TcpPort` 或释放端口后重试;修改会立即生效,无需重启。 - **部分配置修改后不生效**:API 端口与打印通道变更需要停止服务后重新运行。 - **管理台打不开**:请确认 API 端口未被占用,并在服务所在机器访问 `http://127.0.0.1:5990/`。 - **无法出纸**:确认选择了正确的打印机或串口参数,且打印机支持 ZPL 指令;非 ZPL 打印机无法解释该指令。 ## 支持项目 如果有帮助到你,请捐赠失业程序员买菜的零钱,谢谢! 微信收款码