SpiritLabelLibrary C# SDK User Manual

---

1. Overview

SpiritLabel is one of the PrintSpirit Open Platform secondary development tools. A C# wrapper component developed based on the Spirit C library, providing an out-of-the-box label printing solution. Fully retains the functional features of the native C language version, further simplifying the integration of label printing and label editing features in C# desktop applications.

2. System Requirements and Installation

2.1 System Requirements

• .NET 5.0 or higher
• Windows/Linux systems (requires deployment of platform-specific libspirit dynamic library)
• Installed PrintSpirit Desktop Edition (SpiritDesktop)

2.2 Installation Methods

NuGet Installation (Recommended)

SpiritLabel has been published to NuGet. Can be directly installed via NuGet package manager or Visual Studio:

1# Visual Studio Package Manager
2Install-Package SpiritLabel
3
4# Or using dotnet CLI
5dotnet add package SpiritLabel

3. Quick Start

3.1 Sample Code

Please check the examples in the c-sharp subdirectory of the https://github.com/printspirit/spirit_example project. demo-win-gui is a WPF application for Windows, featuring printer selection, printing, label creation and editing.

Demo effect:

3.2 Label Printing Process

 1try 
 2{
 3    // Connect to printer
 4    // "Spirit Image" is the built-in virtual printer of PrintSpirit, generates PNG files in Documents\PrintSpirit\output
 5    // Replace with actual printer name. Supports Windows system printers and ZPL/TSPL/CPCL/ESC/POS printers (driverless)
 6    // Available printers can be obtained via SpiritLabel.PrnLst()
 7    var printer = SpiritLabel.OpenPrinter("Spirit Image");
 8    
 9    // Configure print parameters
10    printer.size(500, 300)          // Set paper size to 50x30mm
11           .quality(Qty.High)       // Set print mode: High quality
12
13    // Create print variables for dynamic data merging
14    var printVars = new Dictionary<string, object> 
15    {
16        { "co_name", "PrintSpirit" },
17        { "name", "Label Printer" }
18    };
19    
20    // Execute printing (supports UUID or local files)
21    printer.Print("acae8013-28db-4b77-a500-1a6052633a22", printVars);
22}
23catch (SpiritException ex)
24{
25    Console.WriteLine($"[ERR] Print failed: {ex.ErrorCode}-{ex.Message}");
26}

Explanation:

• Spirit Image is the built-in virtual printer, generates PNG files in Documents\PrintSpirit\output
• First parameter of printer.Print() supports UUID or local files. UUID will fetch label content from PrintSpirit Official Website

3.3 Label Designer Integration

 1var newLabelPath = @"C:\Labels\product_label.psl";
 2
 3// Create new blank label or copy from template
 4SpiritLabel.NewLabel(
 5    templatePath,
 6    "Label Name",
 7    "Label Description",
 8    1000,  // Width (0.1mm units)
 9    600,   // Height (0.1mm units)
10    203,   // DPI
11    @"C:\Templates\base_template.psl" // Base template (optional)
12);
13
14// Launch designer to edit label
15SpiritLabel.Design(newLabelPath);
16
17// Save new label path for subsequent use

When system integrating, ensure to save the label file path (newLabelPath) in your software system for future printing/editing operations.

4. Core API Details

4.1 Printer Management

Get Printer List

1var printers = SpiritLabel.PrnLst();
2Console.WriteLine($"Detected {printers.Count} printers:");
3foreach (var p in printers)
4{
5    Console.WriteLine($"- {p.Name} ({p.Type})");
6}

This feature auto-discovers Windows printers, USB printers (including mainstream barcode printers using ZPL/TSPL/CPCL/ESC/POS protocols - driverless), and network printers (requires configuration via SpiritDesktop management interface).

Printer Connection Configuration

1var printer = SpiritLabel.OpenPrinter(
2    "Zebra ZT410", 
3    PrinterType.ZPL  // Explicitly specify protocol
4);

4.2 Print Control

Chained Parameter Configuration

1p.row(2)              // Set row count
2 .col(3)              // Set column count
3 .gap(5)              // Set horizontal/vertical spacing
4 .gapX(10)            // Set horizontal gap
5 .gapY(15)            // Set vertical gap
6 .quality(Qty.Hight)  // Set print quality
7 .flush(true)         // Set immediate print flush
8 .Print("TemplateID", vars);

4.3 Exception Handling

1try {
2    // Printing operations...
3}
4catch (SpiritException ex) when (ex.ErrorCode == 0x1001) {
5    // Handle connection errors
6}

4.4 License Management

1// Add enterprise license
2SpiritLabel.AddLicense("SPRT-XXXX-YYYY-ZZZZ");

SDK shares license with desktop version. Can use management interface to add licenses. This function mainly helps developers implement their own license management features.