LabelZoom.Sdk 0.1.2

LabelZoom .NET SDK

Official .NET client for the LabelZoom API. Converts barcode labels between ZPL, EPL, TSPL, DPL, PDF, LabelZoom XML/JSON, and raster images.

Targets netstandard2.0 (so .NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+) and net8.0.

Install

dotnet add package LabelZoom.Sdk

Pre-1.0. The public API is stable in practice and covered by a shared conformance suite, but it stays on 0.x until all seven language SDKs have validated the same contract — two contract-level corrections have already come out of that process.

<details> <summary>Build from source</summary>

git clone https://github.com/labelzoom/labelzoom-sdk.git
cd labelzoom-sdk/dotnet
dotnet build LabelZoom.Sdk.sln

</details>

Quick start

An API key is optional. Without one you get the free tier — watermarked output, first label only, a 1 MB request cap, and no multi-page, JSON-target, or image-to-image conversion.

using LabelZoom.Sdk;

using var client = new LabelZoomClient();          // anonymous; this works

var result = await client.Convert()
    .FromZpl("^XA^FO20,20^A0N,28^FDHello^FS^XZ")
    .ToPng()
    .WithDpi(300)
    .ExecuteAsync();

result.Save("label.png");

With a key — passed explicitly, or picked up from LABELZOOM_API_KEY:

using var client = new LabelZoomClient("lz_live_...");
using var fromEnvironment = new LabelZoomClient();  // reads LABELZOOM_API_KEY

PDF to ZPL, one page, at a fixed label size:

var result = await client.Convert()
    .FromFile(SourceFormat.Pdf, "shipping-label.pdf")
    .ToZpl()
    .WithLabelSize(widthInches: 4f, heightInches: 6f)
    .WithPdfPage(0)                                 // 0-based; omit for every page
    .ExecuteAsync();

Console.WriteLine(result.Text);

Filling variable fields — each record produces one label:

var result = await client.Convert()
    .FromZpl(template)
    .ToPdf()
    .WithData(
        new { name = "ACME Corp", sku = "12345" },
        new { name = "Globex",    sku = "67890" })
    .ExecuteAsync();                                // a 2-page PDF

Formats

Sources (12, plus Url): Zpl Epl Tspl Dpl Xml Json Pdf Png Bmp Gif Jpeg Jpg (an alias for Jpeg)

Targets (8): Zpl Xml Json Pdf Png Bmp Gif Jpeg

SourceFormat and TargetFormat are distinct types, so .ToEpl() does not exist and To(SourceFormat.Pdf) does not compile. EPL, TSPL and DPL are source-only on the server, and the type system says so rather than letting you find out from a 404.

SourceFormat.Url has the server fetch a URL you supply and convert whatever it finds. Validate the URL first if it came from untrusted input.

Options

Only options you actually set are sent. The SDK never fills in a client-side default, so a change to a server default reaches you without an SDK upgrade.

Errors

Every non-2xx becomes a typed exception carrying the server's own message, the raw body, and the X-LZ-Request-Id support handle. The body is never discarded.

try
{
    var result = await client.Convert().FromZpl(zpl).ToJson().ExecuteAsync();
}
catch (LabelZoomForbiddenException ex) when (ex.IsPaidFeature)
{
    // "JSON export is a paid feature" — the most common free-tier failure.
    Console.WriteLine($"{ex.Message} (request {ex.RequestId})");
}
catch (LabelZoomException ex)
{
    // One base type catches them all.
    Console.WriteLine($"{(int)ex.StatusCode}: {ex.Message}");
}

LabelZoomBadRequestException, LabelZoomUnauthorizedException, LabelZoomForbiddenException, LabelZoomNotFoundException, LabelZoomPayloadTooLargeException, LabelZoomRateLimitedException and LabelZoomServerException all derive from LabelZoomException.

LabelZoomValidationException deliberately does not — it means the calling code is wrong, it never reaches the network, and it should not be swallowed by a catch (LabelZoomException) written to handle server failures.

Retries

429, 5xx and transport failures are retried automatically: 3 attempts, 1s/2s/4s with full jitter, honouring a longer Retry-After. Other 4xx responses are returned immediately — a malformed request will not become valid on a second attempt.

using var client = new LabelZoomClient(new LabelZoomClientOptions
{
    MaxRetries = 0,                        // disable
    Timeout = TimeSpan.FromSeconds(30),
});

Dependency injection

services.AddHttpClient("labelzoom");
services.AddSingleton(sp => new LabelZoomClient(new LabelZoomClientOptions
{
    HttpClient = sp.GetRequiredService<IHttpClientFactory>().CreateClient("labelzoom"),
}));

LabelZoomClient is thread-safe and meant to be long-lived. When you supply your own HttpClient, you own its lifetime and the SDK will not dispose it.

Testing your own code

LabelZoomClientOptions.HttpMessageHandler is the stub seam, and SleepAsync lets retry logic be tested without spending the wall-clock time:

var options = new LabelZoomClientOptions
{
    HttpMessageHandler = yourStubHandler,
    UseJitter = false,
    SleepAsync = (delay, _) => { recorded.Add(delay); return Task.CompletedTask; },
};

Running the tests

dotnet test --filter "Category!=Integration"    # offline; no key, no network
dotnet test --filter "Category=Integration"     # hits the real API

The offline suite runs the shared conformance fixtures that every LabelZoom SDK is checked against, and asserts it executed all of them. See docs/CONFORMANCE.md.

License

MIT — see LICENSE.