Caretly 0.1.0

Caretly for .NET

The official .NET client for the Caretly API: render ZPL labels to vector PDF or PNG.

• Targets netstandard2.0 and net8.0, so it runs on .NET Framework 4.6.1+, .NET Core and .NET 5+.
• No runtime dependencies.
• Async throughout, with typed errors and automatic retries that are never billed twice.

Install

dotnet add package Caretly

Quickstart

using Caretly;

using var client = new CaretlyClient("zpl_test_..."); // or set CARETLY_API_KEY

var pdf = await client.RenderAsync("^XA^FO50,50^A0N,50,50^FDHello, world^FS^XZ");
await pdf.SaveToAsync("label.pdf");
Console.WriteLine($"{pdf.PageCount} page(s), {pdf.LabelsBilled} billed");

var png = await client.RenderAsync(zpl, new RenderOptions
{
    Format = RenderFormat.Png,
    Page = 2,
    Dpmm = 12, // 300 dpi
});
await png.SaveToAsync("label.png");

Get an API key in the console. Keys starting with zpl_test_ are free and watermark every label with TEST; zpl_live_ keys are billed per label. The key is optional for a self-hosted server that runs without keys.

Several files in one request

RenderFilesAsync sends files as multipart/form-data. Each file starts from a fresh printer state, and the pages follow in the given order.

var result = await client.RenderFilesAsync(new[]
{
    new ZplFile("shipping.zpl", shippingZpl),
    ZplFile.FromPath("invoice.zpl"),
});
Console.WriteLine(string.Join(", ", result.FilePageCounts)); // pages per file, e.g. "2, 1"

Health check

bool up = await client.HealthAsync(); // GET /health

Configuration

using var client = new CaretlyClient(new CaretlyClientOptions
{
    ApiKey = "zpl_live_...",               // default: CARETLY_API_KEY
    BaseUrl = "http://localhost:3000",     // default: https://caretly.dev
    Timeout = TimeSpan.FromSeconds(60),    // per attempt; default 30 s
    MaxRetries = 3,                        // default 2; 0 disables retries
});

With IHttpClientFactory

Pass your own HttpClient. The client does not dispose it. When BaseUrl is not set, the HttpClient.BaseAddress is used if it has one.

services.AddHttpClient("caretly", http => http.BaseAddress = new Uri("https://caretly.dev"));
services.AddSingleton(sp => new CaretlyClient(
    sp.GetRequiredService<IHttpClientFactory>().CreateClient("caretly"),
    new CaretlyClientOptions { ApiKey = configuration["Caretly:ApiKey"] }));

Render options

Page, Dpmm and IdempotencyKey are checked before sending and throw an ArgumentException when invalid.

Results

RenderResult exposes:

SaveTo(path) and SaveToAsync(path) write Content to a file.

Errors

Every error derives from CaretlyException. Error responses throw a CaretlyApiException subclass with StatusCode, ResponseBody (the server's message) and RetryAfter.

Cancelling the CancellationToken throws an OperationCanceledException, not a CaretlyTimeoutException.

try
{
    await client.RenderAsync(zpl);
}
catch (BadRequestException e)
{
    Console.Error.WriteLine($"Invalid label: {e.ResponseBody}");
}
catch (CaretlyApiException e) when (e.StatusCode >= 500)
{
    Console.Error.WriteLine($"Server error {e.StatusCode}");
}

Retries

429 and 503 responses and connection errors are retried up to MaxRetries times (2 by default). The client waits Retry-After when the server sends it, and otherwise backs off exponentially: 0.5 s, 1 s, 2 s, up to 8 s. Other errors and timeouts are not retried.

When retries are on and you did not set IdempotencyKey, the client generates a UUID once per call and sends it with every attempt, so a retried request is never billed twice.

Development

dotnet build -c Release
dotnet test
dotnet pack -c Release -o artifacts

The tests use a fake HttpMessageHandler and need no network.

Publishing

1. Update <Version> in src/Caretly/Caretly.csproj and add an entry to CHANGELOG.md.

2. Build and pack in CI mode, so Source Link paths are deterministic:

   dotnet pack src/Caretly -c Release -o artifacts -p:ContinuousIntegrationBuild=true
   

3. Push the package; the matching .snupkg symbol package is pushed with it:

   dotnet nuget push artifacts/Caretly.0.1.0.nupkg --api-key "$NUGET_API_KEY" --source https://api.nuget.org/v3/index.json
   

4. Tag the release, for example csharp-v0.1.0.

Links

• Caretly: https://caretly.dev
• Source: https://github.com/jaapieaapie1/zpl/tree/main/clients/csharp

License

MIT. See LICENSE.