PdfVerica 1.1.0

PdfVerica

Friendly, modern .NET helpers on top of the Verica PDF engine.

PdfVerica gives you:

• A fluent PdfBuilder to assemble PDFs without juggling raw font registration and content-stream primitives.
• Async services with CancellationToken for every operation (read, transform, annotate, secure, fill forms, convert, validate compliance).
• Stream overloads so large PDFs don't have to be fully buffered as byte[] in your own code.
• A unified PdfOperationResult with bytes, page count, duration, and warnings.
• A shared PageRangeParser that understands "1-3,5,7-9" once and for all.
• ILogger<T> integration across services.
• AddPdfVerica() for one-line DI registration.

Targets net8.0, net9.0, net10.0.

Install

dotnet add package PdfVerica

Quick start

using PdfVerica;
using PdfVerica.Services;

// 1. Build a PDF from scratch — fluent, no font boilerplate.
var bytes = PdfBuilder.Create()
    .SetMetadata(creator: "MyApp")
    .AddPage(PageSize.A4)
        .DrawRectangle(0, 800, 595, 42, fillColor: RgbColor.FromHex("#1f6feb"))
        .DrawText("Invoice #4242",       x: 40, y: 815, size: 22, fontKey: "F2", color: RgbColor.White)
        .DrawMultilineText("Line 1\nLine 2\nLine 3", x: 40, y: 760)
        .DrawLine(40, 60, 555, 60, color: RgbColor.Gray, width: 0.5)
    .Build();

// 2. Or read existing PDFs.
var reader = new PdfReader();
var info   = await reader.InspectAsync(bytes);        // page count, encryption state
var text   = await reader.ExtractTextAsync(bytes);
var tables = await reader.ExtractTablesAsync(bytes);

Dependency injection

// Program.cs
builder.Services.AddPdfVerica();

// Anywhere
public class InvoiceController(PdfBuilder _, PdfReader reader, PdfTransformer xform) { ... }

AddPdfVerica() registers the stateless services as singletons. PdfBuilder is not registered (each PDF is built from a fresh instance via PdfBuilder.Create()).

Page ranges, one parser everywhere

using PdfVerica;

// "1-3,5,7-9" → zero-based indexes [0,1,2,4,6,7,8]
var indexes = PageRangeParser.ParseIndexes("1-3,5,7-9", pageCount: 10);

// Or as Verica PageRange values (used by Split / Extract)
var ranges  = PageRangeParser.ParseRanges("1-3,5,7-9", pageCount: 10);

// Pretty-print the inverse:
PageRangeParser.Format(new[] { 0, 1, 2, 4, 6, 7, 8 });  // "1-3,5,7-9"

PdfTransformer.SplitAsync(pdf, "1-3,5,7-9") and PdfTransformer.DeletePagesAsync(pdf, "2,4-5") accept the expression directly.

Streaming

Every service has byte[] and Stream overloads where it makes sense:

await using var input  = File.OpenRead("source.pdf");
await using var output = File.Create("text-extracted.txt");

var text = await reader.ExtractTextAsync(input, ct);
await output.WriteAsync(System.Text.Encoding.UTF8.GetBytes(text), ct);

And PdfOperationResult exposes:

var result = await transformer.MergeAsync(new[] { pdf1, pdf2 }, ct);
Console.WriteLine($"{result.PageCount} pages, {result.ByteLength} bytes, took {result.Duration.TotalMilliseconds:F0} ms");
await result.SaveAsync("merged.pdf", ct);
await result.WriteToAsync(httpResponseBody, ct);

Module map

draw.io → PDF

using PdfVerica.Services;

var drawio = new PdfDrawioConverter();

// Auto-detect from bytes (any of .drawio XML, .drawio.svg, .png exports).
var fromFile = await drawio.ConvertAsync(File.ReadAllBytes("flowchart.drawio"), hintFilename: "flowchart.drawio");
await fromFile.SaveAsync("flowchart.pdf");

// Or use the explicit overloads:
await (await drawio.ConvertSvgAsync(File.ReadAllText("flowchart.drawio.svg"))).SaveAsync("flowchart.pdf");
await (await drawio.ConvertXmlAsync(File.ReadAllText("flowchart.drawio"))).SaveAsync("flowchart.pdf");
await (await drawio.ConvertPngAsync(File.ReadAllBytes("flowchart.png"))).SaveAsync("flowchart.pdf");

Notes:

• SVG inputs (.drawio.svg) are rendered with Verica's SVG engine for best fidelity. Recommended for design-heavy diagrams.
• PNG exports must have been saved by draw.io with diagram metadata included (the default). The converter extracts the embedded mxfile chunk and renders it.
• Compressed .drawio files (the default save format) are handled — payloads are base64-decoded and inflated automatically.
• mxGraphModel rendering is best-effort: rectangles, rounded rectangles, ellipses, rhombuses, edges with arrowheads, and cell labels are supported. Complex shape libraries (UML, AWS icons, etc.) fall back to plain rectangles with the cell label — for high fidelity, export to .drawio.svg first.

Password protection

Encryption applies only to a freshly-built document, so it's part of the builder pipeline:

var bytes = PdfBuilder.Create()
    .AddPage(PageSize.A4).DrawText("Secret report", 72, 760, size: 18)
    .WithPasswordProtection(userPassword: "open", ownerPassword: "owner",
        allowPrinting: true, allowCopying: false)
    .Build();

Signing

var signed = await new PdfSecurity().SignWithSelfSignedAsync(
    pdf, signerName: "Demo User", reason: "Approved", location: "Mumbai");

For production use, build your own Verica.Parsing.Signatures.PdfSigningOptions with a real cert and call SignAsync(pdf, options).

Page ranges in Verica use zero-based indices

PdfVerica.PageRangeParser accepts user-friendly one-based expressions and converts to zero-based for you. If you call Verica APIs directly, remember their PageRange is (StartIndex, Count) and PageRange.Inclusive(start, endInclusive) matches the natural "1-3" meaning after subtracting 1.

What's not in v1.1

The OCR (OcrService, TesseractShellOcrEngine) and Barcode (BarcodePng, BarcodeGenerator) modules of the underlying Verica package are intentionally not wrapped — they pull a Tesseract binary dependency and have a separate surface area. If you need them, use Verica directly.

License

MIT