ZplCore 1.0.0

zplCore.com

High Performance .NET Labelprint Engine

.NET 10 library (ZplCore.dll) built on SkiaSharp + HarfBuzz. One assembly contains:

1. ZPL renderer (ZplRenderer): a virtual Zebra printer, ZPL II → PNG / JPEG / WebP / BMP / PDF / GRF / TIFF / GIF / SVG / HTML / EPS / PCX / PCL / EPL / Fingerprint / ESC/POS. Structured diagnostics with source positions.
2. Label model (Labels.Label): items in mm/inch → ZPL, preview, JSON, expressions, mass data binding (LINQ / EF Core / LiteDB).
3. Printing (Printing): TCP 9100, serial, USB, parallel, Windows spooler, CUPS; job settings (^MM ^MN ^MT …), ~HS/~HQES status, USB discovery, dry run, and a virtual TCP 9100 printer (ZplVirtualPrinter).
4. Export (Export.RasterExport, Export.LabelLanguageWriter): PCX, TIFF, EPL, Fingerprint, ESC/POS, PCL.
5. EPL2 renderer (EplRenderer): renders EPL2 through the same engine. ToZpl() is an EPL→ZPL converter.
6. Barcode generator (Barcodes.Barcode): 144 symbologies, with output to PNG/JPEG/WebP, vector SVG/PDF/EPS, ZPL ^GFA, or any SKCanvas.
7. GS1 (Barcodes.Gs1): Application Identifier parser and validator (534 AIs), GS1-128, SSCC-18, ITF-14 and composite codes (CC-A/B/C).

This is an independent implementation based on the public ZPL II specification and the symbology standards.

Documentation: zplcore.com/docs. Full API reference: zplcore.com/api-reference.

Performance: 200,000+ shipping labels per second (real 100 × 150 mm / 4 × 6 in label with 33 elements, QR + Code 128

• GS1-128; dictionary or JSON records → ZPL file, JIT and NativeAOT), 100,000 shipping labels in under half a second, over 1,000 PNG previews per second (all cores) and over 100,000 labels per second straight from C# objects (POCO, JIT). Measured on an Apple M3 Max (14 cores), macOS, .NET 10, median of 5 runs, byte-identical output checked. Details and Docker/NativeAOT results: zplcore.com/performance. Measurements, not a guarantee.

Licence key

zplCore is commercial software (EULA). The licence key is checked offline against its signature: no phone-home, no telemetry, works air-gapped. Without a key everything works in evaluation mode, and previews, images, PDF/SVG and generated ZPL carry a visible "zplCore.com TRIAL" watermark. Register the key once at start-up:

ZplCore.Licensing.ZplCoreLicense.Register(builder.Configuration["ZplCore:License"]!);

Alternatively, set the environment variable ZPLCORE_LICENSE (the key), ZPLCORE_LICENSE_FILE (path of a file), or put a file zplcore.license next to the application. ZplCoreLicense.Status tells you what was found. Keep the key secret and never commit it. Pricing and licensing: zplcore.com/pricing.

Quickstart

using ZplCore;

var renderer = new ZplRenderer(new ZplRenderSettings { Dpi = 203 }.WithLabelSizeMm(100, 150));
List<byte[]> pngs = renderer.ProcessFile("labels.zpl");          // one PNG per label

renderer.Settings.OutputFormat = ZplOutputFormat.Pdf;             // one PDF, one page per label
File.WriteAllBytes("preview.pdf", renderer.ProcessFile("labels.zpl")[0]);

using ZplCore.Labels;

var label = new Label(LabelUnit.Mm, 100, 60)
    .AddFontFile("fonts/Arial.ttf", "ARIAL.TTF")                      // sent to the printer via ~DY
    .Add(new TextItem { X = 5, Y = 5, DataField = "Customer.Name", Font = "E:ARIAL.TTF", FontSize = 14 })
    .Add(new BarcodeItem { X = 5, Y = 20, DataField = "TrackingNo" })
    .Add(new TextItem { X = 5, Y = 50, Expression = "\"Paket \" + LABEL_NUMBER" });

// EF Core: streaming, ^DF template once, then only field values
await label.For<Shipment>()
    .Copies(s => s.Parcels)
    .UseStoredFormat()
    .PrintAsync(new ZplCore.Printing.ZplPrinterClient("192.168.1.50"),
                db.Shipments.Include(s => s.Customer).Where(s => !s.Printed).AsAsyncEnumerable());

// EPL2
var epl = new EplRenderer(new ZplRenderSettings { Dpi = 203 });
List<byte[]> labels = epl.ProcessFile("label.epl");
string zpl = epl.ToZpl(File.ReadAllText("label.epl"));   // migrate EPL forms to ZPL

// Stand-alone barcodes
var bc = new ZplCore.Barcodes.Barcode
{
    Symbology = ZplCore.Barcodes.Symbology.Gs1_128,
    Code = "(01)09521234543213(10)LOT42",
    Unit = ZplCore.Barcodes.BarcodeUnit.Millimeter, BarWidth = 0.33, BarHeight = 20,
};
File.WriteAllText("gs1.svg", bc.ToSvg());
File.WriteAllBytes("gs1.pdf", bc.ToPdf());

// GS1 validation
var r = ZplCore.Barcodes.Gs1.Parse("(01)09521234543213(17)251301");   // r.Errors → invalid date

// ^FN fields: test data for templates (plain labels and ^DF/^XF formats, all labels and ^PQ copies)
var filler = new ZplRenderer(new ZplRenderSettings { FieldValues = new Dictionary<int, string> { [1] = "ACME", [2] = "Vienna" } });
List<byte[]> filled = filler.ProcessFile("template.zpl");       // unknown keys → diagnostic ZPL1301 (INVALID_FIELD_VALUE_KEY)
foreach (var f in ZplCore.Parsing.ZplFields.Find(zpl))          // number, ^FN1"Prompt", default value, ^DF format
    Console.WriteLine($"{f.Number}: {f.Prompt} = {f.Value}");
string merged = ZplCore.Parsing.ZplFields.Fill(zpl, filler.Settings.FieldValues!); // ^FN → ^FD, ^XF expanded

Print jobs from JSON templates (one job: leading label + records + trailing label + cut)

using ZplCore.Labels;

var job = PrintJobTemplate.FromFiles("templates/leading.json", "templates/shipping.json", "templates/trailing.json");
job.JobName = "Tour 7";
job.KeyField = "TrackingNo";          // first/last key on the trailing label
job.CutAfterLastLabel = true;         // ^MMT for all labels, ^MMC only for the last one
job.StoredFormatName = "R:SHIP.ZPL";  // optional: template once, then only field values

string zpl = job.For<Shipment>().ToZpl(db.Shipments.Where(s => !s.Printed).Take(50).ToList());
File.WriteAllText("job.zpl", zpl);    // 52 labels in ONE file

Leading and trailing labels bind to PrintJobInfo: JobName, Created, RecordCount, LabelCount, FirstKey and LastKey.

Features

RFID watermark in previews

Labels with an RFID tag operation (^RF, ^WT, ^WF, ^RQ; ^RS/^RB setup alone does not count) show a grey RFID tag pictogram in previews, like common ZPL viewers: centred, about 0.86" wide (independent of the label size), behind all label content (ink pixels stay unchanged) and turned with ^PO I. SVG and vector PDF get it as a vector path (<g class="rfid-indicator">).

var s = new ZplRenderSettings
{
    RfidIndicator = ZplRfidIndicator.Watermark,   // default; None switches it off
    RfidIndicatorColor = new SKColor(0xC0, 0xC0, 0xC0),
    RfidIndicatorOpacity = 1f,
};

Only PNG, JPEG, WebP, BMP, GIF, PDF, SVG, HTML and EPS show it. Printer languages (GRF, EPL, PCL, Fingerprint, ESC/POS) and the 1-bit TIFF/PCX files never contain it.

Vector output (SVG/PDF)

ZplOutputFormat.Svg produces true vector graphics: frames, lines, circles, ellipses and diagonals (^GB ^GC ^GE ^GD, also rounded and white) as paths (arcs as A segments), barcodes as module rectangles and text as glyph outlines from the same layout as the raster image (HarfBuzz shaping, fonts 0 and A–H, ^FB/^TB, rotations). The SVG therefore looks identical even without the fonts installed and stays sharp at any zoom. Each field is a <g> with data-cmd, data-offset and data-length (the ^FO…^FS source span in the ZPL), so a web UI can map clicks back to ZPL positions.

var renderer = new ZplRenderer(new ZplRenderSettings { Dpi = 203 }.WithLabelSizeMm(100, 150));
List<string> svgs = renderer.RenderSvg(zpl);              // one SVG document per label, independent of OutputFormat

// or via OutputFormat, with options
var settings = new ZplRenderSettings
{
    OutputFormat = ZplOutputFormat.Svg,
    SvgSelectableText = true,       // additional invisible <text> over single-line text fields (selectable/searchable)
    SvgElementAttributes = true,    // data-cmd/data-offset/data-length (default)
};
byte[] svg = new ZplRenderer(settings).ProcessCommands(zpl)[0];

// Vector PDF is the default; PdfVector = false embeds one lossless image per label at label dpi
byte[] pdf = new ZplRenderer(new ZplRenderSettings { OutputFormat = ZplOutputFormat.Pdf }).ProcessCommands(zpl)[0];

• SvgMode = ZplSvgMode.TracedRaster gives the earlier SVG (raster image split into rectangles), ZplSvgMode.EmbeddedRaster embeds the PNG.
• ^GF, ~DG/^XG, ^IM and ^IL are embedded as a 1-bit PNG (<image>) at their position; bitmap fonts loaded via ~DB are split into rectangles pixel-exactly.
• ^FR/^LR (XOR): where the field ink sits over pure black or pure white, the field stays vector (paper or ink colour, e.g. white text on a black bar). Over a mixed background only that field area is embedded as an image from the raster.
• ^PO I, ^PM, ^LH, ^LS, label size, colours, background and watermark image, OutputRotation, Flip and PaperOrientation apply like for the raster image; vector PDF also supports sheet layout.
• Text is never written as font text, always as a path. This avoids Skia's non-thread-safe SVG/PDF text path (DirectWrite on Windows); parallel rendering is safe.
• PdfVector is on by default (sharp at any zoom); PdfVector = false gives the raster PDF. All images in PDFs are embedded losslessly (never JPEG).

Accuracy against a real printer

A ZPL corpus is rendered and compared pixel by pixel, with 2-dot tolerance, against printer-accurate reference renders (Labelary). Mean score 0.974 over 122 cases (79 cases ≥ 0.99). Identical or ≥ 0.99: font 0 in all sizes and rotations, ^FB, ^TB, ^FT, ^FR/^LR, shapes, ^GF, all 1D barcodes, EAN/UPC layout, Code 128 modes, POSTNET, MaxiCode, Aztec.

Zebra behaviour this reproduces: font 0 advance widths per character; QR position offset by the ^BY height, and QR error correction boosting; Code 128 mode N stays in subset B; barcode text overflows outside the field; wide element width is floor(ratio × module); ^TB line pitch is 1.26 × h; font B is uppercase only, font H has no lowercase; ^FN together with ^FD in a stored format is a fixed field.

Limits

• Remaining visual differences to Zebra (all symbols still decode correctly): the DataMatrix encodation when ASCII and Text are the same length; the glyph shapes of the bitmap fonts A–H. Macro PDF417 (^B7 with ^FM) and the MicroPDF417 part of ^BT are not verified against Labelary.
• QR (^BQ, model 2) is module-identical with Labelary: mode segmentation, version, error correction boost and mask (ISO/IEC 18004 penalty on the complete symbol), verified on more than 3,600 symbols (versions 1–33, all levels and masks, manual input modes, GS1, ^CI28). Model 1 (^BQ…,1) is printed as model 2.
• Zebra's resident fonts are proprietary, so DejaVu replaces them. Register the original TTF if you need identical metrics.
• Not implemented (no public specification): Response Plus PostMatrix, Pharmacode 2D, HIBC ISO/IEC 15434 envelope. ISBT 128 helpers cover DS001–DS011 only.
• Experimental: Deutsche Post BZL ([Experimental("ZPLBZL001")]) and JAB Code; the JAB Code encoder is slow (about 0.5 s for 120 random Unicode characters).
• On Linux the glyph rasterisation differs slightly (FreeType vs CoreText).
• All encoders ported from BWIPP are bit-exact against bwip-js; ZXing decode tests are added where ZXing supports the symbology.
• Fingerprint output has not been tested on hardware.

Platforms, scripts and databases

• Verified on macOS, Windows 11, Debian and Azure Linux 3.0 (SDK, runtime and distroless runtime); no native packages required.
• NativeAOT-compatible: ZplCore, ZplCore.VectorLift, ZplCore.Testing, the CLI and the MCP server are IsAotCompatible with 0 trim/AOT warnings; AOT output is byte- and pixel-identical to JIT. POCO binding of nested types needs <TrimmerRootAssembly> (otherwise a MissingMemberException, never empty fields) – or [ZplRecord] on the types (source generator, no reflection).
• World scripts (Arabic, Chinese, Hindi, Korean, Japanese, Russian) render with downloaded Noto TTFs, both via ~DU + ^A@ and as graphics.
• Data binding works with SQLite (EF Core), LiteDB, SQL Server 2022, PostgreSQL and MongoDB.

Command line tool

The CLI ships as the separate .NET tool package ZplCore.Cli (command zplcore): render, convert EPL→ZPL, print to network printers, generate barcodes, validate, format, diff, import, compliance pre-check, scan-proof, Vector-Lift, GS1 2D migration, extract and redact. An MCP server for coding agents ships as ZplCore.Mcp (command zplcore-mcp). See zplcore.com/docs.

Server image, Designer and Capture

• Server image and Helm chart: a container image renders over HTTP (/api/jobs/preview), deployable with the Helm chart. See zplcore.com/server.
• zplCore Designer: embeddable WYSIWYG label editor (NuGet ZplCore.Designer, Docker image, JavaScript SDK @zplcore/designer, Web Component and Blazor). Licensed separately (requires a zplCore SDK licence of the same or a higher tier). See zplcore.com/docs/designer, try it: zplcore.com/editor.
• Artistic codes: logo QR, module and finder shapes, gradient fills and barcode motifs; every designed symbol is read back after rendering and weakened or reported when it does not scan. See zplcore.com/artistic.
• zplCore Capture: Windows app that turns labels from existing label software into zplCore JSON templates by reading only the print job. Provided on request. See zplcore.com/migration.

Trademarks

Zebra, ZPL, ZPL II, EPL and Link-OS are trademarks or registered trademarks of Zebra Technologies Corp. QR Code is a registered trademark of DENSO WAVE INCORPORATED. GS1, GS1 DataBar, GS1 Digital Link, EPC and EPCglobal are trademarks of GS1 AISBL. ESC/POS is a registered trademark of Seiko Epson Corporation, Intelligent Mail a registered trademark of the United States Postal Service and Mailmark a registered trademark of Royal Mail Group Ltd. Other product and company names and logos mentioned are trademarks or registered trademarks of their respective owners. We use these names only to describe compatibility with file formats, printer languages and standards. zplCore.com is an independent product and is not endorsed, sponsored or certified by these companies; compliance packs are pre-checks, not certifications.

Contact: support@zplcore.com