C# quickstart

This page shows how to convert labels from C# with the LabelZoom .NET SDK.

Before you begin

Install .NET Framework 4.6.1 or later, .NET Core 2.0 or later, or .NET 5 or later. The package targets netstandard2.0 and net8.0.
Optional: Get an API key. Without one, output has a watermark. See Authentication.

Install the SDK

Add the LabelZoom.Sdk package from NuGet to your project:

dotnet add package LabelZoom.Sdk

Convert ZPL to PDF

Replace the contents of Program.cs with the following program:

using LabelZoom.Sdk;

using var client = new LabelZoomClient();   // reads LABELZOOM_API_KEY

var result = await client.Convert()
    .FromZpl("^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ")
    .ToPdf()
    .WithLabelSize(widthInches: 4f, heightInches: 6f)
    .WithDpi(203)
    .ExecuteAsync();

result.Save("label.pdf");

The SDK reads your API key from the LABELZOOM_API_KEY environment variable. To pass a key explicitly, use new LabelZoomClient("API_KEY"). The client wraps an HttpClient, so create one client for your application and reuse it.

Run the program with dotnet run. It writes label.pdf.

Convert a PDF to ZPL

var result = await client.Convert()
    .FromFile(SourceFormat.Pdf, "shipping-label.pdf")
    .ToZpl()
    .WithPdfPage(0)                     // 0-based; omit to convert every page
    .ExecuteAsync();

Console.WriteLine(result.Text);

Write PDF, image, and printer-language (EPL, IPL, TSPL, DPL, SBPL) output as bytes (result.Bytes), not text; see Binary output.

Fill variable fields

var template = "^XA^FO50,50^A0N,30,30^FD{name}^FS^FO50,100^A0N,30,30^FD{sku}^FS^XZ";

var result = await client.Convert()
    .FromZpl(template)
    .ToZpl()
    .WithData(                          // one label per record
        new { name = "ACME Corp", sku = "12345" },
        new { name = "Globex", sku = "67890" })
    .ExecuteAsync();

Console.WriteLine(result.Text);

Each placeholder, such as {name}, takes its value from the matching key in each record; see Merge fields for the placeholder syntax.

Handle errors

try
{
    await client.Convert().FromZpl("^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ").ToPdf().ExecuteAsync();
}
catch (LabelZoomException e)
{
    Console.Error.WriteLine($"HTTP {(int)e.StatusCode}, request ID {e.RequestId}: {e.Message}");
}

The SDK retries 429 and 5xx responses automatically before it throws. For status codes, see Errors.

Call the API without the SDK

To call the API with HttpClient instead of the SDK, send the label as the request body. This example uses .NET 6 or later:

using System.Net.Http.Headers;

var zpl = "^XA^FO50,50^ADN,36,20^FDLabelZoom^FS^XZ";
var apiKey = Environment.GetEnvironmentVariable("LABELZOOM_API_KEY");

using var client = new HttpClient();
// The API key is optional. Omit the Authorization header if it isn't set.
if (!string.IsNullOrEmpty(apiKey))
{
    client.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", apiKey);
}

var content = new StringContent(zpl, System.Text.Encoding.UTF8, "text/plain");
var response = await client.PostAsync(
    "https://api.labelzoom.com/api/v2/convert/zpl/to/pdf?label.width=4&label.height=6&dpi=203",
    content);

response.EnsureSuccessStatusCode();
await File.WriteAllBytesAsync("label.pdf", await response.Content.ReadAsByteArrayAsync());

To convert a PDF to ZPL, post a ByteArrayContent with Content-Type: application/pdf to /convert/pdf/to/zpl, and read await response.Content.ReadAsStringAsync().

To set options, send one params query parameter that holds JSON, or use dot notation such as label.width=4. Accept can be */*, the target’s media type, or a wildcard such as image/*. See Conversion parameters.