C#-Client

Der C#-Client ruft die Brevier-Engine aus .NET auf. Sie übergeben HTML und Daten und bekommen das PDF zurück. Er braucht .NET 8 oder neuer. Die Engine übernimmt das Layout, Sie schreiben keinen Code zum Zeichnen von PDFs.

Es gibt zwei Betriebsarten:

Engine installieren

Die Engine ist der Befehl brevier. Der Kindprozess-Modus startet ihn, er muss also im PATH des Rechners liegen, auf dem Ihr .NET-Code läuft:

pip install brevier

Weitere Wege zur Installation stehen auf der Seite Installation.

Testschlüssel holen

Jede Erzeugung braucht einen Lizenzschlüssel, auch zum Testen. Holen Sie den Schlüssel vor der ersten Erzeugung.

1. Fordern Sie auf der Preisseite einen kostenlosen Testschlüssel für 30 Tage an. Er kommt per E-Mail.
2. Setzen Sie die Umgebungsvariable BREVIER_LICENCE_KEY:

export BREVIER_LICENCE_KEY="<ihr-lizenzschluessel>"

$env:BREVIER_LICENCE_KEY = "<ihr-lizenzschluessel>"

Die Engine liest den Schlüssel aus ihrer Umgebung. Der Client gibt Ihre Umgebung an den Kindprozess weiter. Im Serve-Modus setzen Sie den Schlüssel in der Shell, die brevier serve startet.

Client hinzufügen

dotnet add package Brevier

Kindprozess

Dieses Programm erzeugt ein PDF aus einem HTML-Text und einem Dictionary:

using Brevier;

byte[] pdf = await Pdf.Builder()
    .WithHtml("<h1>Hello {{ name }}</h1>")
    .WithData(new Dictionary<string, string> { ["name"] = "World" })
    .ToBytesAsync();

await File.WriteAllBytesAsync("hello.pdf", pdf);

Starten Sie es mit dotnet run. Im Ordner liegt jetzt hello.pdf.

• WithHtml und WithCss nehmen das Layout als Text. WithHtmlFileAsync und WithCssFileAsync lesen es aus einer Datei.
• WithData nimmt jedes C#-Objekt. WithJson nimmt JSON-Text.
• ToBytesAsync gibt das PDF zurück. ToFileAsync schreibt es in einen Pfad.

Serve-Modus

Im Serve-Modus läuft die Engine als Dienst, und Ihr Code fragt sie mit dem Namen einer Vorlage nach einem PDF. Eine Vorlage ist ein Ordner mit einer Datei gleichen Namens:

<!DOCTYPE html>
<html lang="en">
<body>
  <h1>Hello {{ name }}</h1>
</body>
</html>

Starten Sie den Server in dem Ordner, der templates enthält:

brevier serve --templates templates

Der Server lauscht auf 127.0.0.1:8080. Er hat weder TLS noch eine Anmeldung. Stellen Sie ein Gateway davor, bevor Sie ihn nach außen öffnen. Dann erzeugen Sie die Vorlage aus C#:

using Brevier;

byte[] pdf = await new TemplateBuilder("hello", new ConnectOptions { Url = "http://127.0.0.1:8080" })
    .With("name", "World")
    .RenderAsync();

await File.WriteAllBytesAsync("hello.pdf", pdf);

• With(name, value) setzt eine Wurzel der Vorlage. With(dictionary) setzt mehrere.
• Rows(list) setzt die Zeilen einer Tabelle.
• RenderAsync(objects) bindet jedes Objekt an die Wurzel seines Typs.
• Ohne URL liest der Client die Umgebungsvariable BREVIER_URL. Ohne sie startet er brevier serve --stdio als Kindprozess. Er liest den Ordner templates des Arbeitsverzeichnisses und nutzt den Prozess weiter.

Wie erzeuge ich viele PDFs auf einmal?

Pdf.Batch() macht aus jeder HTML-Datei eines Ordners und seiner Unterordner ein PDF. Alle Dateien bekommen dasselbe CSS. Der Batch übergibt keine Daten: Jede Datei muss schon die fertige Seite sein, zum Beispiel aus Ihrer eigenen Template-Engine.

using Brevier;

var batch = await Pdf.Batch().WithInput("briefe", "*.html").WithCssFileAsync("firma.css");
var written = await batch.WithOutput("out").ToFilesAsync();

foreach (var file in written)
{
    Console.WriteLine(file);
}

Mit briefe/2026-001.html und briefe/2026-002.html gibt das Programm eine Zeile je geschriebenem PDF aus, in der Reihenfolge, in der es die Dateien findet:

out/2026-001.pdf
out/2026-002.pdf

Für ein PDF je Datensatz rufen Sie stattdessen Pdf.Builder() in einer Schleife auf. Ein Unterordner von briefe erscheint als derselbe Unterordner von out. Scheitert eine Datei, bricht ToFilesAsync mit einer BrevierException ab.

Wie liefere ich das PDF aus einem Web-Endpunkt aus?

Erzeugen Sie die Bytes und geben Sie sie als Datei mit dem Inhaltstyp application/pdf zurück. In einer Minimal API von ASP.NET Core:

app.MapGet("/invoices/{id}/pdf", async (string id) =>
{
    byte[] pdf = await new TemplateBuilder("rechnung").RenderAsync(await invoices.FindAsync(id));
    return Results.File(pdf, "application/pdf", $"rechnung-{id}.pdf");
});

invoices steht für Ihren eigenen Datenzugriff. Setzen Sie BREVIER_URL auf dem Server, dann geht jeder Aufruf an Ihr laufendes brevier serve. Der Code ändert sich nicht.

Wie bekomme ich HTML statt eines PDFs?

Html.Builder() nimmt dieselben Aufrufe wie Pdf.Builder() und gibt HTML zurück. Damit zeigen Sie das Dokument in einem Webportal, oder Sie vergleichen es in einem Test:

byte[] html = await Html.Builder()
    .WithHtml("<h1>Hello {{ name }}</h1>")
    .WithData(new Dictionary<string, string> { ["name"] = "World" })
    .ToBytesAsync();

Die Klassennamen dieses HTML bleiben von Version zu Version gleich. Ausgabe und Tests zeigt, wie Sie es in einem Snapshot-Test nutzen.

Einen JasperReports- oder Word-Aufruf ersetzen

Wenn Ihr Dienst heute einen JasperReports-Bericht oder eine Word-Datei füllt, importieren Sie zuerst die Vorlage. Ersetzen Sie dann den Aufruf in zwei Schritten.

Schritt 1 behält Ihr Dictionary der Daten und übergibt die Zeilen:

return new TemplateBuilder("kontoauszug").With(data).Rows(buchungen).Render();

Schritt 2 übergibt Ihre Objekte. Der Client bindet jedes Objekt an die Wurzel seines Typs.

return new TemplateBuilder("kontoauszug").Render(konto, kunde, buchungen);

Fehler

Der Client wirft eine BrevierException. Sie hat Code, den Fehlercode der Engine wie DATA_ERROR, und Path, die Stelle in den Daten, an der das Problem liegt. Die Meldung enthält nie einen Wert aus Ihren Daten.