.NET PDF-Generator

Übersetzt von Bit Miracle. Originalartikel von Sergey Bobrovsky

Aktualisiert am 27. April 2026

Mit Docotic.Pdf können Sie PDF-Dokumente erstellen, indem Sie diese aus Strukturelementen wie Seiten, Containern, Textbereichen, Bildern, Links, Kopf- und Fußzeilen, Tabellen, Listen und vielem mehr zusammensetzen. Diese Elemente stehen Ihnen über die Layout-API zur Verfügung, die im kostenlosen Layout-Add-on für Docotic.Pdf enthalten ist. Die API unterstützt außerdem wiederverwendbare, benutzerdefinierte Komponenten.

Die Layout-API ermöglicht es Ihnen, Dokumente vollständig in C#- oder VB.NET-Code mithilfe eines flexiblen Ansatzes zu definieren. Basierend auf dieser Beschreibung kann der vom Add-on bereitgestellte PDF-Generator Dokumente mit beliebig komplexen Layouts erstellen – von einfachen Seiten bis hin zu hochstrukturierten PDF-Berichten.

Grundlagen der PDF-Erstellung

Um mit der Layout-API PDF-Dokumente zu erstellen, benötigen Sie das kostenlose Layout-Add-on. Für die Nutzung der Kernbibliothek und der Add-ons ist außerdem ein Lizenzschlüssel erforderlich. Sie können entweder einen kostenlosen Testschlüssel oder einen gekauften Schlüssel verwenden.

Installieren Sie das Add-on

Die empfohlene Methode ist die Installation des Add-ons über NuGet.

Install-Package BitMiracle.Docotic.Pdf.Layout

Der Paketmanager kümmert sich automatisch um die Abhängigkeiten.

Wenn Sie das Add-on lieber manuell installieren möchten, laden Sie zunächst das ZIP-Archiv mit den Docotic.Pdf-Binärdateien herunter. Entpacken Sie das Archiv und fügen Sie Verweise auf die folgenden DLL-Dateien hinzu:

• BitMiracle.Docotic.Pdf.dll
• BitMiracle.Docotic.Pdf.Layout.dll aus dem Unterordner Layout add-on.

Lizenzschlüssel anfordern

Um die Bibliothek zu testen, fordern Sie einen kostenlosen, zeitlich begrenzten Lizenzschlüssel an, indem Sie das Formular auf der Docotic.Pdf-Downloadseite ausfüllen. Falls Sie bereits eine Lizenz erworben haben, verwenden Sie den Ihnen nach dem Kauf zugesandten Code.

Das Layout-Add-on ist kostenlos und benötigt keine zusätzliche Lizenz. Sie können die Layout-API mit Ihrer bestehenden Docotic.Pdf-Lizenz nutzen.

Hallo Welt! mit der Layout-API

Hier ist ein Beispielcode, der die API verwendet, um ein PDF mit dem klassischen Satz „Hallo Welt!“ zu generieren:

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

PdfDocumentBuilder.Create().Generate("hello.pdf", doc => doc.Pages(pages =>
{
    pages.Content().Text("Hello, world!");
}));

Dieser Code erzeugt eine einseitige PDF-Datei, in der sich der Text in der oberen linken Ecke befindet.

Das Codebeispiel verstehen

Das Beispiel beginnt mit dem Hinzufügen eines Lizenzschlüssels. Ohne Lizenz generiert die Docotic.Pdf-Bibliothek keine Dokumente. Der Code zur PDF-Erstellung beginnt in der nächsten Zeile.

Der Code erstellt eine Instanz des Dokumentgenerators durch Aufruf der statischen Methode PdfDocumentBuilder.Create(). Der Aufruf der Methode Generate startet die PDF-Generierung. Diese Methode akzeptiert zwei Parameter: den Namen der zu erzeugenden Datei und einen Delegaten vom Typ Action<Document>. Das Add-on generiert als Ergebnis des Aufrufs von Generate die Datei hello.pdf.

Um das Layout des PDFs zu bestimmen, ruft der Dokumentgenerator den Delegaten mit einer Document-Instanz auf. Der Code des Delegaten setzt den Dokumentinhalt zusammen. In diesem Beispiel verwendet der Delegat die Methode Pages, um dem Generator einen weiteren Delegaten bereitzustellen, der das Layout der Dokumentseiten definiert.

Der Generator ruft den an die Methode Pages übergebenen Delegaten mit einer PageLayout-Instanz auf. Diese Instanz repräsentiert eine oder mehrere Seiten des Dokuments. Die genaue Seitenzahl hängt vom hinzugefügten Inhalt ab.

Der Seitendelegat ruft die Methode Content auf, um auf den Layout-Container für den Hauptinhalt der Seite(n) zuzugreifen. Ein anschließender Aufruf der Methode Text des Containers fügt den Beispieltext zur Seite hinzu. Eine detaillierte Erklärung der Funktionsweise von Layout-Containern finden Sie im Leitfaden zu Layout-Containern.

Der Dokumentgenerator verteilt den Inhalt automatisch auf die Seiten und erstellt genau so viele Seiten, wie für alle dem Layout-Container des Hauptinhalts hinzugefügten Daten benötigt werden. In diesem Beispiel genügt eine einzige Seite, daher enthält die Ausgabe genau eine Seite.

Häufige Aufgaben, die über die grundlegende Stichprobe hinausgehen

Der Beispielcode erstellt zunächst eine PdfDocumentBuilder-Instanz und ruft anschließend die Generate-Methode auf, um ein PDF zu erzeugen. Sie können den Builder konfigurieren, bevor er mit der PDF-Generierung beginnt.

Beispielsweise können Sie ein verschlüsseltes PDF erzeugen, indem Sie dem Builder einen Verschlüsselungshandler bereitstellen. Sie können außerdem Metadaten angeben, die der Builder in das generierte Dokument aufnehmen soll. Weitere Informationen zur Anpassung des Builders finden Sie in einem separaten Artikel.

Der Beispielcode verwendet nur den Layout-Container des primären Inhaltsbereichs. Es stehen jedoch auch andere Inhaltsbereiche zur Verfügung. Hier ist die vollständige Liste der PageLayout-Methoden für den Zugriff auf Inhaltsbereiche:

• Background() – gibt die Hintergrundebene zurück, die von anderen Inhalten überdeckt wird.
• Header() – gibt die gemeinsame Kopfzeile für alle Seiten zurück.
• Content() – gibt den Hauptinhaltsbereich der Seite zurück.
• Footer() – gibt die gemeinsame Fußzeile für alle Seiten zurück.
• Foreground() – gibt die Vordergrundebene zurück, die über anderen Inhalten angezeigt wird.

Nur der Inhalt des Hauptinhaltsbereichs beeinflusst die Seitenzahl des generierten PDFs. Der Dokumentgenerator wiederholt alle Bereiche außer dem von Content() angegebenen auf jeder Seite. Weitere Informationen zu Inhaltsbereichen finden Sie im Artikel zum Seitenlayout.

Viele Dokumente verwenden unterschiedliche Layouts auf verschiedenen Seiten. Beispielsweise kann die erste Seite ein Cover-Design haben, während die folgenden Seiten ein einfacheres Layout verwenden. Manche Dokumente enthalten spezielle Seiten für Tabellen oder verwenden je nach Abschnitt unterschiedliche Hintergründe. Um solche Dokumente mit Docotic.Pdf und dem Layout-Add-on zu generieren, rufen Sie die Methode Document.Pages mehrmals auf. Ein funktionierendes Beispiel finden Sie in unserem Beispiel-Repository.

Organisation des Codes

Bei kurzem Code, wie im Beispiel, ist es in Ordnung, Aufrufe zu verketten und verschachtelte Lambdas zu verwenden. Bei größeren Projekten ist es jedoch oft praktischer, den Code in separate Methoden aufzuteilen. Dadurch wird der Code lesbarer und wartungsfreundlicher.

So sieht das „Hello, world!“-Beispiel aus, wenn der Code in Methoden aufgeteilt ist.

public void GeneratePdf()
{
    BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

    PdfDocumentBuilder.Create().Generate("hello.pdf", BuildDocument);
}

private void BuildDocument(Document doc)
{
    doc.Pages(BuildPages);
}

private void BuildPages(PageLayout pages)
{
    pages.Content().Text("Hello, world!");
}

Warum sollte man PDFs mit der Docotic.Pdf Layout API generieren?

Die Layout-API ist eine entwicklerfreundliche, moderne Methode zur PDF-Erstellung aus zusammensetzbaren Bausteinen, ohne dass Kenntnisse der PDF-Formatinterna erforderlich sind. Sie ermöglicht die performante und deterministische PDF-Layout-Erstellung. Die API eignet sich ideal für Szenarien mit hohem Dokumentenaufkommen.

Die API ist in Verbindung mit Docotic.Pdf und dem kostenlosen Layout-Add-on verfügbar. Sowohl Docotic.Pdf als auch das Layout-Add-on sind vollständig verwaltete DLLs ohne unsichere Codeblöcke. Die Layout-API kommt ohne externe Abhängigkeiten wie Browser oder Skia-Binärdateien aus und bietet somit eine schlanke, ressourcenschonende Lösung, die sich einfach implementieren und warten lässt.

API-Übersicht

Die Layout-API ist eine intuitive und benutzerfreundliche API. Sie beschreiben das Layout Ihres Dokuments vollständig im Code mithilfe flexibler Layoutelemente. Der Generator ordnet Ihren Inhalt automatisch, paginiert ihn und rendert das Ergebnis als PDF.

Das Layout-Add-on verwendet ein deklaratives, flussbasiertes Layoutsystem. Zu den Layoutelementen gehören Listen, Spalten, Zeilen, Tabellen, Bilder, Textbereiche, Kopf- und Fußzeilen, Container und vieles mehr. Anstatt Elemente manuell an exakten Koordinaten zu platzieren, beschreiben Sie deren Verhalten. Der Dokumentgenerator berechnet anschließend das endgültige Layout und erstellt das PDF.

Das flussbasierte Layoutsystem stellt sicher, dass sich das Layout an Seitengröße und Inhalt anpasst. Dank dieses Systems eignet sich das Add-on hervorragend für komplexe, strukturierte und regelbasierte Layouts. Sie können verschiedene Containertypen verschachteln und anspruchsvolle Strukturen erstellen, ohne die Lesbarkeit zu beeinträchtigen.

Bei der Arbeit mit der Layout-API können Sie die meisten Aufrufe verketten. Dies führt zu kompakterem und ausdrucksstärkerem Code als bei herkömmlichen APIs. Die Reihenfolge der Aufrufe in einer Kette ist wichtig. Alles ist streng typisiert, was Kompiliersicherheit gewährleistet und den Code refaktorierbar macht. Der Code, der die Layout-API verwendet, kann zudem per Unit-Test geprüft werden.

Um Ihre Layout-Implementierung noch kompakter zu gestalten, können Sie die API um eigene Methoden erweitern und eine übersichtliche, ausdrucksstarke domänenspezifische Sprache (DSL) darum herum entwickeln.

Weitere Informationen zur Positionierung und zur Erstellung von DSLs finden Sie im Artikel, der die Steuerung von Größe, Position, Ausrichtung und Rendering-Verhalten von Containern erläutert.

.NET-Versionen und Plattformunterstützung

Sie können die Layout-API in Projekten verwenden, die auf .NET Standard 2.1 und neuere Frameworks abzielen. Das Layout-Add-on ist also mit .NET 5 bis .NET 10 kompatibel. Zusätzlich wird .NET Core 3.0+ unterstützt.

Mit der Layout-API können Sie PDFs in ASP.NET Core, MAUI-Apps, Unity, Xamarin und Konsolenanwendungen generieren. Docotic.Pdf kann mit dem Layout-Add-on PDFs unter Windows, macOS und Linux erzeugen.

Cloud-Plattformen und Docker-Images

Docotic.Pdf mit dem Layout-Add-on ist in Azure- und AWS-Cloud-Umgebungen, einschließlich serverloser Setups, lauffähig. Bibliothek und Add-on unterstützen dynamische Hardwareänderungen, Autoscaling und weitere Cloud-native Laufzeitfunktionen.

In den meisten Cloud-Szenarien ist eine ungebundene Lizenz erforderlich. Die Lizenz-FAQ erklärt, wie Sie die geeignete Lizenz für Cloud-Anwendungen auswählen.

Die Layout-API funktioniert direkt in Docker-Containern. Für die PDF-Generierung ist keine spezielle Konfiguration erforderlich, wenn Sie die Bibliothek und das Layout-Add-on in einem Container ausführen.

Hinzufügen von Text zu PDF-Dateien

Text ist ein grundlegender Bestandteil jedes PDF-Dokuments. Sie können die Text-Methoden der Klasse LayoutContainer verwenden, um einem Inhaltsbereich Text hinzuzufügen.

Textbereiche

Im „Hello, world“-Beispiel habe ich die Überladung LayoutContainer.Text(string) verwendet, um dem primären Inhalt der Seite Text hinzuzufügen. Schauen wir uns nun eine weitere Überladung der Text-Methode an.

public static void GenerateTextPdf()
{
    PdfDocumentBuilder.Create().Generate("text-spans.pdf", doc => doc.Pages(pages =>
    {
        pages.Content().Text(AddTextSpans);
    }));
}

private static void AddTextSpans(TextContainer text)
{
    text.Line("About VB.NET")
        .Style(t => t.Strong);

    text.Span("VB.NET is a multi-paradigm, object-oriented language ");
    text.Span("that runs on .NET, Mono, and the ");
    text.Hyperlink(
        ".NET Framework",
        new Uri("https://dotnet.microsoft.com/download/dotnet-framework"));
    text.Line(".");

    text.Span("Released by Microsoft in 2002, ");
    text.Line("it continues the lineage of the original Visual Basic language.");
}

Dieser Code verwendet die Methoden Span und Line der Klasse TextContainer, um Text in die aktuelle Zeile einzufügen. Die Methode Line vervollständigt die aktuelle Zeile zusätzlich. Der Beispielcode verwendet außerdem die Methode Hyperlink, um einen Link zu einer externen Ressource an einen bestimmten Textabschnitt anzuhängen.

Beachten Sie, wie der Beispielcode die erste Zeile mithilfe der Methode Style formatiert. Betrachten wir das Konzept der Textstile genauer.

Textstile

Mit Textstilen können Sie das Erscheinungsbild von Texten anpassen. Die Klasse TextStyle bietet Methoden zum Ändern von Schriftgröße, Buchstabenabstand, Farben und anderen Texteigenschaften. TextStyle-Objekte sind unveränderlich, daher erzeugt jeder Methodenaufruf eine neue Stilinstanz. Sie können Textstile auf verschiedenen Layoutebenen anwenden.

PdfDocumentBuilder.Create().Generate("text-styles.pdf", doc =>
{
    doc.Pages(pages =>
    {
        pages.TextStyle(TextStyle.Parent.FontSize(30));

        pages.Content()
            .TextStyle(TextStyle.Parent.FontColor(new PdfRgbColor(0, 0, 255)))
            .Text(text =>
            {
                text.Span("Hello,");

                text.Span("World!")
                    .Style(TextStyle.Parent.Underline());
            });
    });
});

Die Eigenschaft TextStyle.Parent gibt einen speziellen Stil zurück, bei dem alle Texteigenschaften undefiniert sind. Im obigen Beispiel wird „Hello, World!“ blau dargestellt, wobei das zweite Wort unterstrichen und die Schriftgröße 30 Punkt verwendet wird.

Dies geschieht, weil der Code:

• die Schriftgröße auf Seitenebene auf 30 Punkt festlegt,
• dann die Textfarbe für den primären Inhaltsbereich auf Blau setzt,
• und anschließend den Unterstreichungsstil auf den letzten Textabschnitt anwendet.

Jeder nachfolgende Stil erbt die vorherigen über die TextStyle.Parent-Eigenschaft.

Mithilfe der Methoden der TextStyle-Klasse können Sie unter anderem die Textrichtung auf rechts nach links ändern. Ein weiteres Beispiel für die Verwendung der Textstilvererbung finden Sie in unserer Beispielsammlung.

Typografie

Die Klasse TextStyle ermöglicht die Anpassung aller Texteigenschaften außer der zugehörigen Schriftart. Um die Standardschriftart zu ändern, verwenden Sie die Methoden von Document.TextStyleWithFont, um einen Textstil basierend auf einer bestimmten Schriftart zu erstellen. Sie können eine im Betriebssystem installierte Schriftart verwenden oder eine aus einer Datei oder einem Datenstrom laden.

Nachdem Sie einen schriftartbasierten Stil erstellt haben, können Sie optionale Eigenschaften hinzufügen und den resultierenden Stil anschließend auf ein Textfeld anwenden. Dieses C#-Beispiel zeigt die Verwendung einer Systemschriftart.

PdfDocumentBuilder.Create().Generate("text-style-with-font.pdf", doc =>
{
    var font = SystemFont.Family("Calibri");
    var style = doc.TextStyleWithFont(font).FontSize(30);

    doc.Pages(pages =>
    {
        pages.Content().Text(text =>
        {
            text.Span("Hello,");

            text.Span("World!")
                .Style(style);
        });
    });
});

Die Methode TextStyleWithFont enthält einen optionalen Parameter, der angibt, wie die Schriftart in das generierte Dokument eingebettet werden soll. Standardmäßig bettet die Bibliothek:

• die verwendeten Glyphen für TrueType-/OpenType-Schriftarten ein,
• alle Glyphen für Type1- und CFF-Schriftarten ein,
• keine Glyphen für integrierte PDF-Schriftarten (Base14-Schriftarten) ein.

Aufgrund dieser Standardeinstellungen können Dokumente, die TrueType- und OpenType-Schriften verwenden, selbst bei Verwendung großer Schriftarten klein bleiben. Sie können außerdem einen benutzerdefinierten Schriftartenlader, Ausweichschriftarten und eine Behandlung für fehlende Glyphen festlegen. Details zur Schriftartenverwaltung in PDF-Dokumenten finden Sie im Beispielcode in unserem Beispiel-Repository.

Die Layout-API bietet eine Sammlung vordefinierter Stile, auf die Sie über die Klasse Typography zugreifen und sie bearbeiten können.

PdfDocumentBuilder.Create().Generate("typography.pdf", doc =>
{
    doc.Typography(t =>
    {
        var fontsPath = Environment.GetFolderPath(Environment.SpecialFolder.Fonts);
        var arialFont = new FileInfo(Path.Combine(fontsPath, "arial.ttf"));

        t.Document = doc.TextStyleWithFont(arialFont);
        t.Header = t.Parent.FontSize(20).FontColor(new PdfGrayColor(20));
        t.Footer = t.Footnote;
    });

    doc.Pages(pages =>
    {
        pages.Header().AlignCenter().Text("Header");

        pages.Content().Text(t =>
        {
            t.Line("Title").Style(t => t.Title);
            t.Line("Heading 1").Style(t => t.Heading1);
            t.Line("Regular");
        });

        pages.Footer()
            .Height(20)
            .AlignCenter()
            .Text(t => t.CurrentPageNumber());
    });
});

Ich empfehle, die vordefinierten Stile durch die Konfiguration der Typografie für das gesamte Dokument zu überschreiben. Dies ist jedoch nicht zwingend erforderlich; Sie können Textstile weiterhin auf Textbereichsebene anwenden.

Mit der Klasse Typography müssen Sie keine Textstilreferenzen in Variablen speichern. Stattdessen registrieren Sie die benötigten Stile mithilfe der Methoden von Document.Typography und greifen später über die Eigenschaften des Typography-Objekts darauf zu. Im Beispiel zur Typografie sehen Sie, wie Sie vordefinierte und benutzerdefinierte Textstile beim Generieren von PDF-Dokumenten verwenden.

Arbeiten mit Kopf- und Fußzeilen

Viele PDF-Dokumente aus der Praxis, wie Berichte oder Rechnungen, enthalten Kopf- und Fußzeilen. In diesem Abschnitt erfahren Sie, wie Sie beides in eine PDF-Datei einfügen.

public static void GeneratePdfWithHeaderAndFooter()
{
    PdfDocumentBuilder.Create()
        .Generate("header-footer.pdf", doc => doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6).Margin(10);

        BuildPagesHeader(pages.Header());
        BuildPagesFooter(pages.Footer());

        pages.Content().Text("Hello, world!");
    }));
}

public static void BuildPagesHeader(LayoutContainer header)
{
    header.TextStyle(TextStyle.Parent.FontSize(8))
        .AlignRight()
        .Text(t =>
        {
            t.Line($"Created by: {Environment.UserName}");
            t.Line($"Date: {DateTime.Now}");
        });
}

public static void BuildPagesFooter(LayoutContainer footer)
{
    footer.AlignRight().Text(text =>
    {
        text.Style(t => t.Parent.FontColor(new PdfRgbColor(255, 0, 0)));

        text.CurrentPageNumber();
        text.Span(" / ");
        text.PageCount();
    });
}

Die Methode BuildPagesHeader verkleinert die Schriftgröße des Headertextes. Der Headerinhalt besteht aus zwei Zeilen: einer mit dem Namen des aktuellen Benutzers und einer mit dem aktuellen Datum. Der Text ist rechtsbündig.

Beachten Sie, dass der Code keine explizite Größe für den Header festlegt. Er füllt die gesamte Seitenbreite abzüglich der linken und rechten Ränder aus, und seine Höhe hängt von der Höhe der Textzeilen ab.

Die Methode BuildPagesFooter zeigt, wie die aktuelle Seitenzahl in der PDF-Fußzeile platziert wird. Die Bibliothek berechnet die aktuelle Seitenzahl und die Gesamtseitenzahl automatisch. Sie können auf diese Werte mit den Methoden CurrentPageNumber und PageCount eines TextContainer-Objekts zugreifen.

Die Layout-API bietet außerdem eine Möglichkeit zur Formatierung von Seitenzahlen. Beispielsweise können Sie hexadezimale Seitenzahlen wie folgt darstellen:

text.CurrentPageNumber().Format(p => "0x" + p?.ToString("x2"));

Unser Beispiel-Repository enthält ein weiteres Beispiel für das Hinzufügen von Kopf- und Fußzeilen zu einer PDF-Datei. In diesem Beispiel werden Seitenzahlen als römische Ziffern formatiert.

Bilder einfügen

Wie man so schön sagt: Ein Bild sagt mehr als tausend Worte. In Angeboten oder Quittungen fügen Sie oft Ihr Firmenlogo oder ein anderes wichtiges Bild ein. In diesem Beispiel verwende ich ein einfaches, ansprechendes Bild.

Um ein Bild zu verwenden, müssen Sie es zunächst dem Dokument hinzufügen. Die Bibliothek kann Bilder aus einer Datei oder einem Datenstrom laden. Unterstützt werden ausschließlich Rasterformate: PNG, JPEG, JPEG 2000, BMP, GIF und TIFF.

Sobald Sie ein Image-Objekt haben, können Sie es als Inhalt eines oder mehrerer Layout-Container festlegen, indem Sie die Image-Methode des Containers aufrufen. Sie können das Bild wie jeden anderen Inhalt skalieren, drehen, mit Abständen versehen und anordnen.

PdfDocumentBuilder.Create().Generate("image-with-text.pdf", doc =>
{
    var imageFile = new FileInfo("red-flowers-at-butterfly-world.jpg");
    var image = doc.Image(imageFile);

    doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6);
        pages.Content().Column(c =>
        {
            c.Spacing(20);

            c.Item()
                .AlignCenter()
                .Text("Hello, world!")
                .FontSize(20);

            c.Item()
                .AlignCenter()
                .MaxWidth(200)
                .Image(image);
        });
    });
});

Der Beispielcode verwendet sowohl Text als auch ein Bild im Hauptinhaltsbereich. Ein Layout-Container kann jedoch entweder nur Text oder nur ein Bild enthalten. Um beides im Hauptinhaltsbereich der Seite einzubinden, benötigen Sie einen zusammengesetzten Container.

Ich verwende einen Column-Container, um Text und Bild vertikal hintereinander anzuordnen. Die Item-Methode des Spalten-Containers erstellt einen Untercontainer. Ein Aufruf von Item erzeugt einen Container für den Text, ein weiterer einen für das Bild. Der zusammengesetzte Container mit all seinen Untercontainern bildet den Hauptinhalt.

Um den Beispielcode auszuführen, laden Sie das Blumenbild aus unserem Beispiel-Repository herunter und legen Sie es im Arbeitsverzeichnis Ihrer Anwendung ab.

Online-Bilder

Wenn Sie nur eine Bild-URL anstelle einer Datei haben, laden Sie das Bild in einen Speicherstream und erstellen Sie daraus ein Image-Objekt. Das folgende Beispiel zeigt, wie Sie Online-Bilder mit der Layout-API verwenden.

public static async Task AddImageWithTextFromUrl()
{
    using var http = new HttpClient();
    using var stream = await http.GetStreamAsync("url/to/image");

    var memoryStream = new MemoryStream();
    await stream.CopyToAsync(memoryStream);
    memoryStream.Position = 0;

    PdfDocumentBuilder.Create().Generate("online-image-with-text.pdf", doc =>
    {
        var image = doc.Image(memoryStream);

        doc.Pages(pages =>
        {
            pages.Size(PdfPaperSize.A6);
            pages.Content().Column(c =>
            {
                c.Spacing(20);

                c.Item()
                    .AlignCenter()
                    .Text("Hello, world!")
                    .FontSize(20);

                c.Item()
                    .AlignCenter()
                    .MaxWidth(200)
                    .Image(image);
            });
        });
    });
}

Da die Methode asynchrone Operationen ausführt (Herunterladen eines Bildes von einer URL), wird sie als async Task und nicht als void deklariert. Aufrufer müssen mit await auf die Methode warten, um sicherzustellen, dass die PDF-Generierung korrekt abgeschlossen wird. In Ihrem eigenen Code kann eine ähnliche Methode auch einen Wert zurückgeben; in diesem Fall würde sie als async Task<TResult> deklariert.

Listen erstellen

Was ist eine Liste? Man kann sie sich als eine Gruppe nummerierter Elemente vorstellen, die untereinander geschrieben sind. Die Layout-API bietet keinen speziellen Containertyp für Listen, aber es ist einfach, einen solchen mithilfe anderer zusammengesetzter Container zu implementieren.

var dayNames = DateTimeFormatInfo.InvariantInfo.DayNames;
var dayNamesSpain = DateTimeFormatInfo.GetInstance(new CultureInfo("es-ES")).DayNames;

PdfDocumentBuilder.Create().Generate("list.pdf", doc => doc.Pages(pages =>
{
    pages.Size(PdfPaperSize.A6);
    pages.Content().Column(column =>
    {
        for (int i = 0; i < dayNames.Length; i++)
        {
            column.Item().Row(row =>
            {
                row.Spacing(5);
                row.AutoItem().Text($"{i + 1}.");
                row.RelativeItem().Text(t =>
                {
                    t.Line(dayNames[i]);
                    t.Line($"In Spain they call it {dayNamesSpain[i]}");
                });
            });
        }
    });
}));

Der Beispielcode erstellt die Liste als Spalte mit Zeilen. Jede Zeile enthält zwei Elemente: Das erste (links) enthält die Elementnummer, das zweite (rechts) den Elementtext. Der Code legt den Abstand zwischen den Elementen in jeder Zeile explizit fest.

Um die Elemente anzuordnen, muss der Row-Container entweder die Größe jedes Elements explizit angeben oder berechnen. In diesem Beispiel werden die Methoden AutoItem und RelativeItem verwendet. Dadurch berechnet der Zeilencontainer die für das erste Element benötigte Breite und verwendet die verbleibende Breite für das zweite Element.

Mit diesem Ansatz und der Anpassung des Erscheinungsbilds der Zeilen nach Bedarf können Sie eine Liste erstellen, die optimal zum Layout und Stil Ihres Dokuments passt.

Bautabellen

Viele PDF-Dokumente enthalten Tabellen, was nicht verwunderlich ist, da Tabellen die Übersichtlichkeit und Strukturierung der Daten verbessern. Dieser Abschnitt zeigt, wie man mithilfe der Layout-API eine Tabelle in einem PDF erstellt.

public static void AddTable()
{
    PdfDocumentBuilder.Create().Generate("table.pdf", doc => doc.Pages(pages =>
    {
        pages.Size(PdfPaperSize.A6);

        var color = new PdfGrayColor(75);
        pages.Content().Padding(20).Table(t =>
        {
            t.Columns(c =>
            {
                c.RelativeColumn(4);
                c.RelativeColumn(1);
                c.RelativeColumn(4);
            });

            t.Header(h =>
            {
                h.Cell().Background(color).Text("Month");
                h.Cell().Background(color).Text("Days");
                h.Cell().Background(color).Text("First Day");
            });

            var year = DateTime.Now.Year;
            for (int yearDiff = 0; yearDiff < 4; yearDiff++)
            {
                for (int i = 11; i >= 0; i--)
                {
                    var stats = GetMonthStats(year - yearDiff, i);

                    t.Cell().Text(stats.Item1);
                    t.Cell().Text(stats.Item2);
                    t.Cell().Text(stats.Item3);
                }
            }
        });
    }));
}

private static (string, string, string) GetMonthStats(int year, int monthIndex)
{
    return (
        $"{DateTimeFormatInfo.InvariantInfo.MonthNames[monthIndex]} {year}",
        DateTime.DaysInMonth(year, monthIndex + 1).ToString(),
        new DateTime(year, monthIndex + 1, 1).DayOfWeek.ToString()
    );
}

Der Beispielcode erstellt eine einfache Tabelle mit grundlegenden Informationen zu den Monaten des aktuellen Jahres und der drei Vorjahre. Der Code definiert drei Spalten mit relativen Breiten. Die beiden äußersten Spalten sind viermal so breit wie die mittlere.

Der Code definiert außerdem die Tabellenüberschrift, indem er Kopfzeilenzellen hinzufügt und für jede Zelle Text und Hintergrundfarbe festlegt. Passt eine Tabelle nicht auf eine Seite, wird die Kopfzeile auf jeder Seite wiederholt, die die Tabelle belegt. Dieses Verhalten ist in der vom Beispielcode generierten PDF-Datei sichtbar.

Zwei einfache Schleifen werden verwendet, um die Zeilen zu erstellen. Die äußere Schleife durchläuft die Jahre, die innere Schleife die Monate in umgekehrter Reihenfolge. Die innere Schleife ruft die Informationen zu jedem Monat ab und fügt dann drei Zellen hinzu, um eine Zeile zu bilden.

Weitere Details finden Sie in dem Artikel, der die Funktionen des Tabellencontainers ausführlich erläutert.

Interne PDF-Links erstellen

PDF-Dokumente unterstützen interne Links, die es Lesern ermöglichen, innerhalb derselben Datei zu einer anderen Stelle zu springen. In einem PDF-Viewer werden diese Links als anklickbare Text- oder Bildelemente dargestellt. Sie funktionieren wie Hyperlinks, verweisen aber nicht auf eine externe Website, sondern navigieren innerhalb des Dokuments selbst.

Viele PDF-Dokumente verwenden interne Links für Lesezeichen oder ein Inhaltsverzeichnis, um Lesern das schnelle Navigieren zwischen Abschnitten zu erleichtern. Hier erfahren Sie, wie Sie mithilfe der Layout-API einen Link zu einem Dokumentabschnitt hinzufügen können:

PdfDocumentBuilder.Create().Generate("link.pdf", doc =>
{
    doc.Pages(pages =>
    {
        pages.Content().Column(c =>
        {
            const string SectionName = "Chapter 1";
            c.Item().SectionLink(SectionName).Text("Link");

            c.Item().PageBreak();

            c.Item().Section(SectionName).Text("Target");
        });
    });
});

Der Beispielcode verknüpft den Text auf der ersten Seite mit dem Abschnitt mit dem angegebenen Namen. Dies geschieht durch Aufruf der Methode SectionLink des Layout-Containers, der den Text enthält. Der Abschnitt kann zu diesem Zeitpunkt bereits existieren oder noch nicht. Der Text ist in einem PDF-Viewer anklickbar.

Anschließend markiert der Code den Text auf der zweiten Seite als Beginn des gleichnamigen Abschnitts. Sein Erscheinungsbild und Verhalten bleiben unverändert, er wird jedoch zum Ziel des Links auf der ersten Seite. Dies geschieht durch Aufruf der Methode Section des entsprechenden Layout-Containers.

In diesem Beispiel sind sowohl der Link als auch sein Ziel Textabschnitte (Spans). Sie können jedoch Abschnitte und Links in jedem beliebigen Layout-Container erstellen. Dies kann ein Container mit einem Bild, ein Tabellencontainer oder ein selbst erstellter Container sein.

Ein Beispiel für die Erstellung eines PDF-Inhaltsverzeichnisses finden Sie in unserer Beispielsammlung.

Gestaltung komplexer PDF-Layouts

Die Layout-API bietet eine Vielzahl von Layout-Containern, die Sie kombinieren können, um beliebig komplexe PDF-Dokumente zu erstellen. Sie können die API auch mit eigenen Komponenten erweitern.

Die Beispiele auf dieser Seite sind bewusst einfach gehalten, um übersichtliche Dokumente zu erstellen, damit Sie sich auf die Kernideen konzentrieren können, ohne sich in Details zu verlieren. Wenn Sie sehen möchten, wie verschiedene Container kombiniert werden können, um ein komplexeres PDF zu generieren, schauen Sie sich das entsprechende Beispiel in unserem Beispiel-Repository auf GitHub an.

Neben der Verwendung integrierter Container können Sie benutzerdefinierte Layoutkomponenten definieren und verwenden. Diese Komponenten sind besonders nützlich, wenn Sie Daten und Layoutlogik in einer einzigen Klasse kapseln möchten. Dadurch, dass alles an einem Ort gespeichert ist, lässt sich die Komponente leichter verstehen, modifizieren und wiederverwenden. Gleichzeitig bietet sie Ihnen eine flexible Möglichkeit, komplexe Layouts zu handhaben.

Um eine benutzerdefinierte Layoutkomponente zu erstellen, implementieren Sie die ILayoutComponent-Schnittstelle in Ihrer Klasse. Beim Generieren eines PDFs ruft die Bibliothek die Compose-Methode der Schnittstelle auf und stellt ein LayoutContext-Objekt bereit. Ihr Code kann dieses Objekt verwenden, um Layoutelemente zu erstellen und auf Informationen über das generierte Dokument zuzugreifen.

Um Ihrem Layout eine benutzerdefinierte Layoutkomponente hinzuzufügen, rufen Sie die Component-Methode der LayoutContainer-Klasse auf. Bezüglich Größe und Positionierung verhält sich eine benutzerdefinierte Komponente wie Text oder Bilder.

Ein Beispiel für die Implementierung einer benutzerdefinierten Komponente mit der ILayoutComponent-Schnittstelle finden Sie im Beispiel Layout-Komponenten.

Weitere Möglichkeiten zur PDF-Erstellung

Docotic.Pdf bietet verschiedene Möglichkeiten zur PDF-Erstellung, die jeweils für unterschiedliche Anwendungsfälle geeignet sind. In diesem Abschnitt wird erläutert, wann die Layout-API sinnvoll ist und wann andere Ansätze besser geeignet sein können.

Wann sollte man die Layout-API bevorzugen?

Die Docotic.Pdf Layout-API ist eine leistungsstarke Methode zur PDF-Generierung aus strukturierten Layouts. Sie ermöglicht die Erstellung von Dokumenten durch die Komposition von Text, Bildern, Containern und Tabellen zu beliebig komplexen, verschachtelten Strukturen. Der Generierungsprozess ist schnell, speicherschonend und verhält sich vorhersehbar.

Docotic.Pdf und das Layout-Add-on bilden ein schlankes, vollständig eigenständiges Paket. Die API benötigt keine externen Bibliotheken oder Browser zur PDF-Generierung. Dies macht sie zur idealen Wahl für .NET-Microservices, Cloud-Anwendungen (insbesondere serverlose) und andere Umgebungen, in denen der Ressourcenverbrauch eine wichtige Rolle spielt.

Da das Dokumentlayout im Code definiert ist, können Sie jeden Teil davon per Unit-Test prüfen. Die Layoutlogik lässt sich wie jeder andere Code wiederverwenden, und Sie können sowohl Daten als auch das Layoutverhalten in benutzerdefinierten Komponenten kapseln.

Alternativen zur Layout-API

Ein eigener Artikel bietet einen detaillierten Vergleich aller Methoden zur PDF-Erstellung mit Docotic.Pdf. Nachfolgend sind einige der gebräuchlichsten Alternativen aufgeführt.

• HTML-zu-PDF-Konvertierung
  Verwendet vorhandene HTML/CSS-Vorlagen wieder. Wählen Sie den HTML-zu-PDF-Ansatz, wenn Ihr Team bereits Dokumente in HTML/CSS erstellt und Sie PDF-Versionen dieser Dokumente benötigen.

• Niedrigstufige PDF-Generierung
  Bietet die maximale Kontrolle über PDF-Struktur und -Inhalt innerhalb der Bibliothek. Wählen Sie diese Option, wenn Sie pixelgenaue Positionierung oder komplexe Vektorgrafiken benötigen. Diese Vorgehensweise empfiehlt sich für leistungskritische Szenarien oder wenn ein möglichst geringer Speicherbedarf erforderlich ist.

• Vorlagenbasierte PDF-Generierung
  Bietet eine schnelle und zuverlässige Möglichkeit, Dokumente auszufüllen, ohne deren Elemente gestalten oder anordnen zu müssen. Wählen Sie diese Option, wenn Sie über eine vordefinierte PDF-Struktur verfügen, z. B. genehmigte oder für Compliance-Zwecke bestimmte Vorlagen, und lediglich Textfelder ändern, Platzhalter ersetzen, zugehörige Dokumente anhängen und ähnliche Aufgaben ausführen müssen.

• PDF-Zusammenführung und -Zusammenstellung
  Hiermit können Sie eine PDF-Datei aus vorhandenen Elementen erstellen, anstatt sie von Grund auf neu zu erstellen. Wählen Sie diese Option, wenn Sie Bilder, gescannte Seiten oder andere PDFs haben, die zu einer einzigen Datei zusammengeführt werden sollen.

Vergleich mit anderen PDF-Generierungslösungen

Dieser Abschnitt enthält zwei Vergleichstabellen: eine mit den wichtigsten Erkenntnissen und eine weitere mit detaillierten, strukturierten Informationen darüber, wie Docotic.Pdf mit dem Layout-Add-on im Vergleich zu anderen gängigen Lösungen zur PDF-Erstellung abschneidet.

Wichtigste Erkenntnisse aus dem Vergleich

Es gibt zahlreiche leistungsstarke Optionen zur PDF-Erstellung, darunter auch kostenlose. Allerdings variieren die Funktionen wie Signieren, Verschlüsseln oder Zusammenführen von Dokumenten, was die Auswahl der für Ihre Bedürfnisse wirklich geeigneten Tools einschränken kann.

Detaillierter Vergleich

Schauen Sie sich die Tabelle an, um den größeren Zusammenhang zu verstehen und Ihre eigenen Schlussfolgerungen zu ziehen.

Abschluss

Docotic.Pdf mit dem Layout-Add-on bietet eine moderne, leistungsstarke und qualitativ hochwertige Möglichkeit, PDFs in C# und VB.NET zu erstellen. Die Bibliothek generiert Berichte, Kontoauszüge, Rechnungen und ähnliche Dokumente. Ihre durchdachte und intuitive API bietet ein optimales Entwicklererlebnis. Sie können sich auf den professionellen Support von Bit Miracle für Docotic.Pdf und seine Add-ons verlassen.

Im Gegensatz zu manch anderen PDF-Generierungslösungen ist Docotic.Pdf eine vollwertige PDF-API. Die Bibliothek kann generierte PDFs mit digitalen Signaturen signieren, einschließlich LTV-fähiger Signaturen. Docotic.Pdf kann Zertifikate verwenden, die auf sicherer Hardware wie USB-Tokens und Smartcards gespeichert sind. Cloudbasierte Hardware-Sicherheitsmodule (HSMs) wie Microsoft Azure Key Vault und AWS Key Management Service (KMS) werden ebenfalls unterstützt.

Mit Docotic.Pdf können Sie den generierten PDFs unterstützende Dokumente wie Tabellen oder Sprachnotizen hinzufügen. Um Dokumente auf einer Webseite oder in einer ähnlichen Oberfläche anzuzeigen, können Sie Miniaturansichten von einer oder mehreren Seiten erstellen.

Nächste Schritte: – Sehen Sie sich die Codebeispiele für die Layout-API an. – Vergleichen Sie die PDF-Generierung aus zusammensetzbaren Bausteinen mit anderen Ansätzen zur PDF-Erstellung. – Kontaktieren Sie uns bei Fragen, Feedback oder speziellen Anwendungsfällen.