15LabelEngine SDK Integration

15.1 Overview

LabelEngine is the core engine SDK of the aBiao label printing system, located in AbiaoLabel.Shared.dll. By referencing this DLL, your system can complete the full workflow: template loading → data binding → script evaluation → ZPL generation → printing, without relying on BarTender or other third-party software.

15.2 Adding the Reference

Option 1: NuGet Package

# Add nupkg to local source
nuget add AbiaoLabel.Shared.1.0.0.nupkg -Source D:\nuget-local

# Project reference
dotnet add package AbiaoLabel.Shared -s D:\nuget-local

Option 2: Direct DLL Reference

<Reference Include="AbiaoLabel.Shared">
  <HintPath>path\AbiaoLabel.Shared.dll</HintPath>
</Reference>

Option 3: Source Code Subproject

git clone <repo-url>
Add existing project → AbiaoLabel.Shared\AbiaoLabel.Shared.csproj

15.3 Installation Requirements

SDK requires aBiao Label Designer (v2.1+) to be installed. The installation directory contains the core DLLs:

Your project should reference AbiaoLabel.Shared.dll and copy the following dependency DLLs to a local folder (e.g. lib/):

lib/
├── zxing.dll                 # Barcode generation
├── zxing.presentation.dll    # Barcode WPF support
├── Microsoft.CodeAnalysis.CSharp.Scripting.dll
├── Microsoft.CodeAnalysis.CSharp.dll
├── Microsoft.CodeAnalysis.Common.dll
├── Microsoft.CodeAnalysis.Scripting.Common.dll
├── System.Drawing.Common.dll
├── System.Private.Windows.Core.dll
└── System.Private.Windows.GdiPlus.dll

Complete dependency sets can be found in WEB/SDKTest/lib/ and WEB/ZplStudio/lib/.

Project Configuration

<ItemGroup>
  <Reference Include="AbiaoLabel.Shared">
    <HintPath>C:\Program Files\iBarcode\AbiaoLabel.Shared.dll</HintPath>
  </Reference>
</ItemGroup>

See sample projects:

• WEB/SDKTest/ — Full LabelEngine example
• WEB/ZplStudio/ — ZPL preview tool

15.4 Quick Start

using AbiaoLabelDesigner.Services;

var engine = new LabelEngine();
engine.LoadTemplate(@"C:\templates\weight-label.iba");
engine.SetData(new Dictionary<string, object>
{
    ["PNAME"] = "Screw",
    ["PZHONGLIANG"] = "105",
    ["PTIAOMA"] = "1234567890"
});
await engine.PrintAsync("Zebra-1");

15.5 API Reference

Template Loading

// Load .iba template from file
engine.LoadTemplate(@"C:\templates\label.iba");

// Load from JSON string
engine.LoadTemplateFromJson(jsonString);

Template Creation (from code)

Create a complete .iba template and save it without the designer:

// Create blank template (100mm × 60mm, 2 columns × 3 rows)
engine.CreateTemplate("My Label", 100, 60, cols: 2, rows: 3);

// Add text component
engine.AddComponent("Title", ComponentType.Text, 10, 5, 80, 10);
engine.SetProperty("Title", "Content", "Hello World");
engine.SetProperty("Title", "FontSize", 24);
engine.SetProperty("Title", "IsBold", true);

// Add barcode
engine.AddComponent("Barcode", ComponentType.Barcode, 10, 20, 70, 20);
engine.SetProperty("Barcode", "Content", "1234567890");
engine.SetProperty("Barcode", "BarcodeFormat", "CODE_128");

// Save as .iba file
engine.SaveTemplate(@"C:\templates\new-label.iba");

Supported component types:

Component Lookup

// Find single component by Name (returns LabelComponent?)
var comp = engine.FindComponent("LOGO");

// Find components by SharedName
var group = engine.FindComponentsBySharedName("Weight Area");

// Find by type
var texts = engine.FindComponentsByType<TextComponent>();
var barcodes = engine.FindComponentsByType<BarcodeComponent>();

Setting Component Properties

// Single property
engine.SetProperty("LOGO", "ImagePath", @"C:\logo.png");
engine.SetProperty("ProductName", "Content", "Screw");
engine.SetProperty("ProductName", "FontSize", 24);
engine.SetProperty("ProductName", "IsBold", true);
engine.SetProperty("WeightText", "IsPrintable", weight > 100);

// Batch set
engine.SetProperties("ProductName",
    ("Content", "Screw"),
    ("FontSize", 24),
    ("IsBold", true)
);

All properties accessible via the Properties panel are supported:

Type Casting (Alternative to SetProperty)

var logo = engine.FindComponent("LOGO") as ImageComponent;
if (logo != null)
{
    logo.ImagePath = @"C:\logo.png";
    logo.Width = 80;
}

Data Binding

// Variable binding + condition evaluation + script evaluation (full workflow)
engine.SetData(new Dictionary<string, object>
{
    ["PNAME"] = Text1.Text,
    ["PZHONGLIANG"] = lblZL.Caption,
    ["PTIAOMA"] = GenerateBarcode()
});

// Variable binding only (no script or condition evaluation)
engine.BindVariables(new Dictionary<string, object>
{
    ["PNAME"] = "Screw"
});

Printable Component Control

// Set whether a component should print
engine.SetProperty("WeightText", "IsPrintable", weight <= 100);
engine.SetProperty("NGMark", "IsPrintable", status == "NG");

// Get list of printable components
var printable = engine.GetPrintableComponents();

Script Control (Set IsPrintable in C# Script)

Write in the component's script editor:

// Don't print this component when weight exceeds 100
if (Weight > 100)
{
    IsPrintable = false;
    return "Overweight, won't print";
}
return $"Weight: {Weight}kg";

Global variables available in scripts: Weight, Price, Quantity, ProductName, Status, IsPrintable

ZPL Generation

// Generate ZPL for printable components only
string zpl = engine.GenerateZPL();
string zpl200 = engine.GenerateZPL(dpi: 200);

// Save to file
File.WriteAllText(@"C:\output.zpl", zpl);

Printing

// Direct printing (sends ZPL via Windows printer driver)
await engine.PrintAsync("Zebra-1");
await engine.PrintAsync("Zebra-1", copies: 2);

// GDI bitmap printing (supports non-ZPL printers)
await engine.PrintWithGdiAsync("HP-LaserJet");
await engine.PrintWithGdiAsync("HP-LaserJet", copies: 3);

Note: PrintAsync uses the Win32 RawPrinter API (OpenPrinter → WritePrinter) to send ZPL commands directly to the Windows printer driver, the same method as BarTender. PrintWithGdiAsync is suitable for non-ZPL printers.

Template Information

double w = engine.LabelWidthMm;   // Template width in mm
double h = engine.LabelHeightMm;  // Template height in mm
int rows = engine.LabelRows;      // Number of label rows
int cols = engine.LabelCols;      // Number of label columns

15.6 License & Trial

SDK licensing is independent from the Label Designer. On first run, a 90-day trial is automatically activated (counted from installation date).

• Full functionality during trial period
• Purchase a license code to activate after trial expires
• Machine code format: GD:XXXXXXXXXXXXXXXX or HW:XXXXXXXXXXXXXXXX
• Without a license, PrintAsync / PrintWithGdiAsync will throw a license exception

15.7 Complete Example

Full runnable projects: WEB/SDKTest (WPF example with UI and printing logic) and WEB/ZplStudio (ZPL preview tool).

Comparison with VB6 + BarTender

' ===== VB6 + BarTender (Before) =====
Set btFormat = btApp.Formats.Open(App.Path & "\lab\weight-label.btw")
btFormat.SetNamedSubStringValue "PNAME", Text1.Text
btFormat.SetNamedSubStringValue "PZHONGLIANG", lblZL.Caption
btFormat.Objects.Find("LOGO").PicturePath = App.Path & "\logo.png"
btFormat.Printer = cbPrinter.Text
btFormat.IdenticalCopiesOfLabel = Val(Text10.Text)
btFormat.PrintOut

// ===== C# + LabelEngine (Now) =====
var engine = new LabelEngine();
engine.LoadTemplate(@".\lab\weight-label.iba");

engine.SetProperty("LOGO", "ImagePath", @".\logo.png");
engine.SetData(new Dictionary<string, object>
{
    ["PNAME"] = Text1.Text,
    ["PZHONGLIANG"] = lblZL.Text
});

await engine.PrintAsync(cbPrinter.Text, copies: int.Parse(Text10.Text));

Full Label System Workflow

using AbiaoLabelDesigner.Services;

public class LabelPrintHelper
{
    private readonly LabelEngine _engine = new();

    public async Task<bool> PrintLabel(string templatePath, LabelData data, string printerName)
    {
        try
        {
            _engine.LoadTemplate(templatePath);

            // Set component properties
            _engine.SetProperty("LOGO", "ImagePath", data.LogoPath);
            _engine.SetProperty("Barcode", "Content", data.Barcode);

            // Variable binding + script evaluation
            _engine.SetData(new Dictionary<string, object>
            {
                ["PNAME"] = data.ProductName,
                ["PZHONGLIANG"] = data.Weight,
                ["PSTATUS"] = data.Status
            });

            // Print
            return await _engine.PrintAsync(printerName, data.Copies);
        }
        catch (Exception ex)
        {
            Log.Error(ex, "Print failed");
            return false;
        }
    }
}

public class LabelData
{
    public string LogoPath { get; set; } = "";
    public string Barcode { get; set; } = "";
    public string ProductName { get; set; } = "";
    public string Weight { get; set; } = "";
    public string Status { get; set; } = "";
    public int Copies { get; set; } = 1;
}

15.8 NuGet Packaging

# Generate .nupkg
dotnet pack AbiaoLabel.Shared\AbiaoLabel.Shared.csproj -c Release -o publish_output

# Output file
publish_output\AbiaoLabel.Shared.1.0.0.nupkg