02ZplRenderer

ZplRenderer verarbeitet ZPL-Strings, Byte-Arrays (Codepage 850 wie am Drucker oder UTF-8 mit BOM) und Dateien. Pro gedrucktem Etikett entsteht ein kodiertes Bild – bei PDF ein Dokument mit einer Seite pro Etikett.

Einstellungen (ZplRenderSettings)

var settings = new ZplRenderSettings
{
    Dpi = 300,                                   // 152, 203, 300 oder 600
    OutputFormat = ZplOutputFormat.Webp,         // Png, Jpeg, Webp, Bmp, Pdf, Grf
    Quality = 90,                                // JPEG/WebP
    AntiAlias = false,                           // reines 1-Bit wie am Thermodrucker
    InkColor = new SKColor(0x1d, 0x3b, 0x8a),    // Farbband
    BackgroundColor = SKColors.LightYellow,      // Etikettenpapier
    OutputRotation = ZplRotation.Rotate90,
    TraceElements = true,                        // Positionen aller Felder sammeln
    Clock = () => new DateTime(2026, 10, 18),    // deterministische ^FC-Felder
}.WithLabelSizeInches(4, 6);

string json = settings.ToJson();                 // speichern ...
var restored = ZplRenderSettings.FromJson(json); // ... und laden

using var watermark = SKBitmap.Decode("muster.png");
var renderer = new ZplRenderer(new ZplRenderSettings
{
    WatermarkImage = watermark,
    WatermarkOpacity = 0.35f,
    ThumbnailSize = 200,              // Ausgabe auf max. 200 px verkleinern
    RenderOutputIndexes = [0, 2],     // nur Etikett 1 und 3 kodieren
    DrawRfid = true,                  // ^RF-Daten als Kasten einzeichnen
});

// PDF: Metadaten + mehrere Etiketten pro Bogen (A4 @ 203 dpi)
var pdf = new ZplRenderer(new ZplRenderSettings
{
    OutputFormat = ZplOutputFormat.Pdf,
    PdfTitle = "Lieferung 42", PdfAuthor = "Lager", PdfSubject = "Versand", PdfKeywords = "zpl",
    PaperWidth = 1680, PaperHeight = 2376, PaperMargin = 40, LabelGap = 16,
}.WithLabelSizeMm(100, 50));
byte[] sheet = pdf.ProcessCommands(zpl)[0];

Wasserzeichen

RFID sichtbar (DrawRfid)

Mehr dazu auf zplCloud.com: Guide: Etikettengröße und Material (^PW, ^LL)

Ausgabeformate & Bitmaps

var renderer = new ZplRenderer(new ZplRenderSettings { OutputFormat = ZplOutputFormat.Tiff }.WithLabelSizeMm(100, 60));
byte[] tiff = renderer.ProcessCommands(zpl)[0];         // EIN mehrseitiges 1-Bit-TIFF

foreach (var format in new[] { ZplOutputFormat.Pcx, ZplOutputFormat.Pcl, ZplOutputFormat.Epl,
                               ZplOutputFormat.Fingerprint, ZplOutputFormat.EscPos })
{
    renderer.Settings.OutputFormat = format;            // je Etikett ein Byte-Array
    List<byte[]> outputs = renderer.ProcessCommands(zpl);
}

// Hintergrund (z. B. vorgedrucktes Formular) und Wasserzeichen aus Datei, data:-URI oder Base64;
// URLs nur asynchron (größenbegrenzt): ZplRenderSettings.LoadImageFromUrlAsync(new Uri("https://…"))
var preview = new ZplRenderSettings()
    .WithBackgroundImage("formular.png")
    .WithWatermarkImage("muster.png", opacity: 0.3f);
SKBitmap logo = ZplRenderSettings.LoadImage("data:image/png;base64,iVBORw0KGgo…");

var renderer = new ZplRenderer(new ZplRenderSettings { TraceElements = true });
foreach (ZplRenderResult result in renderer.Render(zpl))
{
    using SKBitmap bmp = result.Bitmap;              // Aufrufer besitzt die Bitmaps
    foreach (var e in result.Elements)
        Console.WriteLine($"{e.Command} @ {e.X},{e.Y} {e.Width}x{e.Height}: {e.Content}");
    File.WriteAllText("label.grf.zpl", ZplExport.ToGrfZpl(bmp));  // als ^GFA-Grafik
}

Online ausprobieren auf zplCloud.com: ZPL zu PDF · ZPL zu PNG · ZPL zu JPG · ZPL zu SVG

Hintergrund & Wasserzeichen aus Datei, URL oder Base64

ZplRenderSettings.LoadImage(source) lädt Bilder aus Dateipfad, http(s)-URL, data:-URI oder reinem Base64. WithBackgroundImage legt ein Bild (z. B. ein eingescanntes Vordruck-Formular) unter das Etikett, WithWatermarkImage eines darüber – siehe Code oben und das Wasserzeichen-Beispiel.

Ereignisse, Statusabfragen & ~WC

Befehle ohne Bildwirkung (Medien, Schwärzung, Kalibrierung, ~HS …) lösen PrinterControl aus; Antworten auf Host-Abfragen landen in Responses. LabelRendered feuert nach jedem kodierten Etikett. ~WC druckt ein Konfigurationsetikett.

var renderer = new ZplRenderer();
renderer.PrinterControl += (_, e) =>
{
    Console.WriteLine($"Steuerbefehl {e.Command.Prefix}{e.Command.Name} {e.Command.Parameters}");
    // e.Response ist für ~HS vorbelegt und kann überschrieben werden
};
renderer.LabelRendered += (_, e) =>
    File.WriteAllBytes($"label{e.Index + 1}.png", e.Data);

renderer.ProcessCommands("~SD25^XA^MD10^FO50,50^GB100,100,4^FS^XZ~HS");
var status = ZplPrinterStatus.Parse(renderer.Responses[0]);
Console.WriteLine(status.IsReady ? "bereit" : "Fehler");

~WC Konfigurationsetikett

Gespeicherte Formate

Formate (^DF/^XF), Grafiken (~DG, ~DY, ^IS) und Schriften liegen in renderer.Store (ZplResourceStore), der auch zwischen mehreren Renderern geteilt werden kann (new ZplRenderer { Store = shared }).

Druckerspeicher: ^DF / ^XF, ^IS / ^IL

var renderer = new ZplRenderer();

// ^DF speichert ein Format im Druckerspeicher, ^XF ruft es auf, ^FN füllt die Felder
renderer.ProcessCommands("^XA^DFR:ADR.ZPL^FS^FO50,50^A0N,40,40^FN1^FS^FO50,110^A0N,30,30^FN2^FS^XZ");
var labels = renderer.ProcessCommands(
    "^XA^XFR:ADR.ZPL^FN1^FDMax Mustermann^FS^FN2^FDGraz^FS^XZ" +
    "^XA^XFR:ADR.ZPL^FN1^FDErika Muster^FS^FN2^FDWien^FS^XZ");

// Speicher bleibt zwischen Aufrufen erhalten – wie bei einem echten Drucker
Console.WriteLine(string.Join(", ", renderer.Store.Formats));
renderer.Store.AddGraphic("R:LOGO.GRF", SKBitmap.Decode("logo.png"), dither: true);
renderer.Reset();                      // Power-on-Reset (~JR)

^XA^FO10,10^GB300,80,3^FS^FO30,30^A0N,40,40^FDFormular^FS
^ISR:FORM.GRF^XZ                 ← Etikett als Bild speichern (und drucken)
^XA^ILR:FORM.GRF                 ← Bild als Hintergrund laden
^FO30,120^A0N,30,30^FDVariable Daten^FS^XZ

Mehr dazu auf zplCloud.com: Guide: ^DF · Guide: ^XF

^FN-Felder befüllen: FieldValues

ZplRenderSettings.FieldValues (IReadOnlyDictionary<int, string>) setzt die Daten aller Felder mit ^FN-Nummer – in normalen Labels und in mit ^XF aufgerufenen Formaten, für alle Labels und ^PQ-Kopien eines Aufrufs. Der Wert hat Vorrang vor einem ^FD-Vorgabewert und vor dem ^XF-Datenblock; ^FH, ^FC und ^SN/^SF wirken weiter. Schlüssel ohne passendes ^FN meldet das Diagnostic ZPL1301 (ZplDiagnosticCodes.InvalidFieldValueKey, INVALID_FIELD_VALUE_KEY) am ersten Label. ZplFields.Find listet die Felder mit Prompt (^FN1"Name") und Vorgabewert, ZplFields.Fill liefert das befüllte ZPL. CLI: zplcore render label.zpl --field 1=ACME --field 2=Wien.

Online ausprobieren auf zplCloud.com: ZPL Template Filler

Mehr dazu auf zplCloud.com: Guide: ^FN

// ^FN-Felder ohne ^DF/^XF befüllen: Testdaten für Vorschau oder ERP-Vorlagen
const string template = "^XA^FO50,50^A0N,40,40^FN1\"Name\"^FDMuster^FS^FO50,110^A0N,30,30^FN2\"Ort\"^FS^XZ";
var renderer = new ZplRenderer(new ZplRenderSettings
{
    FieldValues = new Dictionary<int, string> { [1] = "Erika Muster", [2] = "Wien" },
});
var png = renderer.ProcessCommands(template);      // gilt für alle Labels, auch in ^XF-Formaten

// Felder für ein Formular auflisten (Nummer, Prompt, Vorgabewert)
foreach (var f in ZplFields.Find(template))
    Console.WriteLine($"^FN{f.Number} {f.Prompt}: {f.Value}");

// ZPL mit eingesetzten Werten (^DF/^XF zu normalen Labels zusammengeführt)
string filled = ZplFields.Fill(template, renderer.Settings.FieldValues!);

Seriennummern, Uhr, ^MC, ^RF

^MC Map Clear

^MCN lässt das Bild für das nächste Etikett stehen (Overlay), ^MCY löscht wieder.

^RF RFID-Wasserzeichen

Etiketten mit RFID-Operation (^RF, ^WT, ^WF, ^RQ) zeigen in der Vorschau ein graues RFID-Symbol: zentriert, ca. 0,86" groß, hinter dem Inhalt, mit ^PO I gedreht; in SVG/Vektor-PDF als Pfad. Nur PNG/JPEG/WebP/BMP/GIF/PDF/SVG/HTML/EPS – nie in GRF, EPL, PCL, Fingerprint, ESC/POS oder 1-Bit-TIFF/PCX. RfidIndicator = ZplRfidIndicator.None schaltet es ab.

^SO / ^ST

Zweit- und Drittuhr mit Versatz (z. B. Mindesthaltbarkeit +2 Monate) bzw. Uhr stellen. ^CD/^CC/^CT ändern die Steuerzeichen, ^TO kopiert gespeicherte Objekte, ^JM halbiert die Punktdichte.

Mehr dazu auf zplCloud.com: Guide: ^SN