Wie man PDF-Dokumente in C# und VB.NET erstellt

Übersetzt von Bit Miracle. Originalartikel von Vitaliy Shibaev

Aktualisiert am 6. Mai 2026

Dieser Artikel beschreibt verschiedene Möglichkeiten, PDF-Dokumente in .NET mithilfe der Docotic.Pdf-Bibliothek zu erstellen. Es handelt sich um eine leistungsstarke, reine C# .NET-Bibliothek ohne externe Abhängigkeiten zum Erstellen, Bearbeiten, Konvertieren und Verarbeiten von PDF-Dokumenten.

In den folgenden Abschnitten stelle ich die wichtigsten Vorgehensweisen zur PDF-Erstellung mit Docotic.Pdf vor:

• Verwendung der Core-API, die detaillierte Kontrolle über Text, Grafiken und interne PDF-Strukturen bietet. Diese Option eignet sich am besten für benutzerdefinierte Layouts, grafikintensive Dokumente und erweiterte Funktionen.
• Verwendung der Layout-API, die Absätze, Tabellen, Kopf- und Fußzeilen sowie automatische Seitennummerierung unterstützt. Diese API ist ideal, wenn Sie strukturierte Dokumente benötigen, ohne Positionen manuell berechnen zu müssen.
• Konvertierung von HTML in PDF mit Unterstützung für SVG und andere Webformate. Diese Vorgehensweise ist besonders nützlich, wenn Ihre Lösung bereits HTML-Dokumente erzeugt und Sie PDF-Versionen dieser HTML- und CSS-Dateien benötigen.
• Erstellung von PDFs aus Bildern. Diese Methode eignet sich für gescannte Dokumente, bildbasierte Berichte, Belege und alle Workflows, die mit Rasterbildern beginnen.
• Zusammenführen oder Aufteilen von PDFs. Dies ist eine gute Wahl zum Erstellen von Berichten, Verarbeiten von Benutzer-Uploads, Zusammenführen verwandter Dokumente und Umstrukturieren großer PDFs.
• Erstellung von PDFs aus Vorlagen. Diese Vorgehensweise eignet sich gut, wenn eine einheitliche Formatierung für stapelweise generierte Dokumente wie Quittungen, Steuerformulare, Arbeitsverträge und andere wiederkehrende Dokumenttypen erforderlich ist.

Weitere im Leitfaden behandelte Themen sind:

• Interaktive Funktionen wie Links und JavaScript-Aktionen
• Vorgehensweisen zum Testen der PDF-Ausgabe, um die erwarteten Ergebnisse sicherzustellen.

PDFs mit der Core-API erstellen

Die Core-API bildet die Grundlage für die PDF-Erstellung in Docotic.Pdf. Sie ermöglicht die vollständige und detaillierte Steuerung von Text, Bildern und Vektorgrafiken auf einer PDF-Zeichenfläche mithilfe der Canvas-API. Diese Zeichen-API ist eine Teilmenge der Core-API und stellt die Methoden und Eigenschaften bereit, mit denen Inhalte zu Seiten und anderen Objekten mit Zeichenflächen hinzugefügt werden können. Neben dem Rendern unterstützt die Core-API auch Anmerkungen, Formularfelder, Ebenen, Lesezeichen und weitere PDF-Funktionen.

Hier ist C#-Code, der ein einfaches PDF mithilfe von drei grundlegenden Operationen erstellt: Text zeichnen, ein Bild platzieren und Vektorgrafiken auf einer Zeichenfläche rendern.

using var pdf = new PdfDocument();
var canvas = pdf.Pages[0].Canvas;

canvas.Font = pdf.CreateFont(PdfBuiltInFont.HelveticaBold);
canvas.FontSize = 14;
canvas.DrawString(40, 100, "Core API demo: text, images, and vector graphics");

var image = pdf.CreateImage("image.png");
canvas.DrawImage(image, 40, 180, 120, 120, 0);

canvas.Pen.Color = new PdfRgbColor(30, 60, 160);
canvas.Pen.Width = 2;
canvas.Brush.Color = new PdfRgbColor(200, 230, 255);
canvas.DrawRectangle(new PdfRectangle(200, 200, 150, 80), PdfDrawMode.FillAndStroke);

pdf.Save("core-api-demo.pdf");

Diese Übersicht stellt nur einen kleinen Teil der Möglichkeiten der Core API vor. Weiterführende Informationen finden Sie im ausführlichen Artikel zum Erstellen von PDFs mit der Core API. Der Artikel behandelt unter anderem das Messen von Text, das Arbeiten mit Farbräumen, das Anwenden von Clipping, das Füllen von Bereichen mit Mustern und den Umgang mit Transparenz.

PDF-Erstellung mit der Layout-API

Die Layout-API ist eine leistungsstarke Dokumentenerstellungs-Engine, die die einfachste und effizienteste Methode zur Generierung komplexer, inhaltsreicher PDFs bietet.

Mit der API setzen Sie PDFs aus Strukturelementen wie Seiten, Containern, Textabschnitten, Bildern, Tabellen, Links, Kopf- und Fußzeilen und mehr zusammen. Anstatt Koordinaten zu berechnen oder die Seitennummerierung manuell zu verwalten, beschreiben Sie die Dokumentstruktur, und die Layout-Engine kümmert sich um den Rest.

Dieses Beispiel veranschaulicht die Erstellung eines PDFs mithilfe der Layout-API und nutzt dabei deklaratives Layout anstelle manueller Positionierung.

PdfDocumentBuilder.Create()
    .Info(info => info.Title = "Docotic.Pdf Layout API demo")
    .Generate("layout-api-demo.pdf", doc => doc.Pages(pages =>
    {
        pages.Content().Padding(100).Text(text =>
        {
            text.Span("The Layout API lets you compose PDFs from structural elements ");
            text.Line("without manually calculating coordinates or handling pagination.")
                .Style(s => s.Strong);
        });
    }));

In der ausführlichen Anleitung erfahren Sie, wie Sie die Layout-API beim Generieren von PDFs in .NET-Anwendungen verwenden.

Konvertierung von Webinhalten mit der HTML-zu-PDF-API

Docotic.Pdf bietet zusammen mit dem kostenlosen Add-on HtmlToPdf eine moderne, hochwertige, Chrome-basierte HTML-zu-PDF-Engine. Mit der API des Add-ons können Sie modernes HTML und andere Webinhalte wie SVG- oder WebP-Bilder in hochwertige PDF-Dokumente umwandeln.

Die HTML-zu-PDF-API erstellt PDFs aus kompletten HTML-Seiten oder HTML-Fragmenten. Sie können Inhalte aus URLs, HTML-Zeichenketten und lokalen HTML-Dateien konvertieren. Die beiden letztgenannten Optionen erleichtern die PDF-Generierung aus HTML-Vorlagen.

Hier ein Beispiel für die PDF-Erstellung aus einer HTML-Vorlage:

public static async Task HelloHtmlTemplate()
{
    static string GetUserName()
    {
        // Replace with real logic: form input, API call, config, etc.
        return "World";
    }

    string html = $@"
        <h1>Hello, {GetUserName()}!</h1>
        <p>This PDF was generated from an HTML template.</p>";

    using var converter = await HtmlConverter.CreateAsync();
    using var pdf = await converter.CreatePdfFromStringAsync(html);
    pdf.Save("hello-html-template.pdf");
}

Weitere Details und Beispiele finden Sie in unserer ausführlichen HTML‐zu‐PDF-Übersicht.

PDFs aus Bildern erstellen

Docotic.Pdf bietet eine flexible und entwicklerfreundliche Möglichkeit, Bilder in PDF zu konvertieren. Die Bibliothek unterstützt über die Core-API die Bildformate JPEG, BMP, GIF, PNG, TIFF und JPEG 2000.

Sofern vom PDF-Format unterstützt, bettet Docotic.Pdf Bilddaten unverändert ein, ohne Pixel zu dekodieren und neu zu kodieren, um die ursprüngliche Komprimierung zu erhalten. Die Bibliothek erhält nach Möglichkeit auch den Farbraum.

Zusätzlich werden SVG- und WebP-Formate über die HTML-zu-PDF-API unterstützt. Wenn Sie Bilder neben Beschriftungen oder Beschreibungen platzieren möchten, hilft Ihnen die Layout-API dabei, Elemente mit minimalem Aufwand anzuordnen und auszurichten.

Wie man mehrere Bilder in einer PDF-Datei zusammenfügt

Mit Docotic.Pdf können Sie ganz einfach mehrere Bilder in eine einzige PDF-Datei umwandeln und dabei jedes Bild auf einer eigenen Seite platzieren.

Das folgende Beispiel lädt Bilder aus Dateien und stellt jedes Bild auf einer eigenen Seite dar. Jedes Bild wird an die Seitengröße angepasst und zentriert, um ein sauberes und einheitliches Layout zu gewährleisten.

public static void ImagesOnToPdf(string[] imagePaths, string outputPath)
{
    using var pdf = new PdfDocument();

    foreach (string path in imagePaths)
    {
        var image = pdf.CreateImage(path);

        var page = pdf.AddPage();
        var pageWidth = page.Width;
        var pageHeight = page.Height;

        var scale = Math.Min(pageWidth / image.Width, pageHeight / image.Height);
        var drawWidth = image.Width * scale;
        var drawHeight = image.Height * scale;
        var x = (pageWidth - drawWidth) / 2;
        var y = (pageHeight - drawHeight) / 2;

        page.Canvas.DrawImage(image, x, y, drawWidth, drawHeight, 0);
    }

    pdf.RemovePage(0);

    pdf.Save(outputPath);
}

Umgang mit mehrseitigen TIFF- und GIF-Bildern

Docotic.Pdf unterstützt mehrseitige TIFF- und GIF-Dateien vollständig. Wenn Sie Bilder in eine PDF-Datei einfügen, verwenden Sie die Methode OpenImage anstelle von CreateImage, falls eines der Bilder mehrere Seiten umfassen kann.

Der folgende Code zeigt, wie Sie TIFF in PDF konvertieren. Er funktioniert sowohl für einseitige als auch für mehrseitige Bilder:

public static void OddFramesToPdf(string[] imagePaths, string outputPath)
{
    using var pdf = new PdfDocument();
    foreach (string path in imagePaths)
    {
        var imageFrames = pdf.OpenImage(path);
        for (int i = 0; i < imageFrames.Count; i++)
        {
            if (i % 2 != 0)
                continue;

            var image = pdf.CreateImage(imageFrames[i]);
            var page = pdf.AddPage();

            page.Width = image.Width;
            page.Height = image.Height;

            page.Canvas.DrawImage(image, 0, 0, image.Width, image.Height, 0);
        }
    }

    pdf.RemovePage(0);

    pdf.Save(outputPath);
}

Mit demselben Verfahren lässt sich auch ein GIF in ein PDF konvertieren. Dies gilt auch für andere Bildformate, ist aber für Formate, die nur ein einzelnes Bild enthalten, unnötig aufwendig.

Zusammenführen und Aufteilen von PDFs

Als vollwertige .NET-Bibliothek kann Docotic.Pdf neue PDFs erstellen, indem Seiten aus bestehenden Dokumenten zusammengeführt, extrahiert und neu angeordnet werden.

Beim Zusammenführen von PDFs fügt die Bibliothek nicht nur Seiten aus einem anderen Dokument hinzu, sondern auch Ebenen, Lesezeichen, Seitenbeschriftungen, gemeinsam genutztes JavaScript, Zielseiten (Links) und eingebettete Dateien. Weitere Informationen und Hinweise zur Reduzierung der Größe kombinierter PDFs finden Sie im Artikel zum Thema PDFs zusammenführen.

Digital signierte PDFs können nicht zusammengeführt werden, ohne die vorhandenen Signaturen ungültig zu machen. Um die Signaturen zu erhalten, erstellen Sie ein PDF-Portfolio anstatt Dokumente anzuhängen. Alternativ können Sie die PDFs zuerst zusammenführen und anschließend eine neue digitale Signatur auf das kombinierte Dokument anwenden.

Mit Docotic.Pdf können Sie außerdem Seiten in neue Dokumente kopieren und extrahieren. Alle Inhalte der kopierten Seiten bleiben erhalten, einschließlich Anmerkungen, Formularfelder, strukturierter Inhalte, Ebenen und anderer zugehöriger Daten. Praktische Beispiele finden Sie im Artikel zum Aufteilen von PDFs in .NET. Dort wird auch erklärt, wie Seiten extrahiert oder entfernt werden.

Arbeiten mit PDF-Vorlagen

PDF-Vorlagen sind vorgefertigte PDF-Dateien, die als Basisstruktur für die Erstellung neuer Dokumente dienen. Sie sind nützlich, wenn Sie PDFs mit einem einheitlichen Layout benötigen, die jedoch unterschiedliche Daten enthalten. Auch wenn Sie das visuelle Design von den eigentlichen Daten trennen möchten, sind PDF-Vorlagen eine gute Wahl.

Vorlagen können entweder formularbasierte oder statische PDFs ohne Formulare sein. Beide Typen erfüllen denselben Zweck. Formularbasierte Vorlagen enthalten zudem interaktive Elemente, die, sofern sie nicht reduziert werden, Informationen von Nutzern erfassen können.

Erstellen von PDFs aus formularbasierten Vorlagen

Formularbasierte Vorlagen enthalten üblicherweise AcroForms, den Standard für interaktive PDF-Formulare, der weit verbreitet ist. Um aus einer solchen Vorlage ein PDF zu erstellen, müssen Sie in der Regel Folgendes tun:

• Jedes Platzhalterfeld ausfüllen
• Die Felder reduzieren, um weitere Bearbeitungen zu verhindern
• Das Ergebnis als neues PDF speichern

Hier ist C#-Code, der ein Platzhaltertextfeld anhand seines Namens findet, ihm einen Wert zuweist, das Feld reduziert und das Ergebnis speichert. Dadurch wird aus der Vorlage ein PDF erstellt:

var nameOnCertificate = "Eva Marin";
using var pdf = new PdfDocument("certificate-template.pdf");
if (pdf.TryGetControl("name", out var field))
{
    if (field is PdfTextBox nameField)
    {
        nameField.Text = nameOnCertificate;
        nameField.Flatten();
    }
}

pdf.Save($"certificate-{nameOnCertificate}.pdf");

Enthält Ihre Vorlage viele Platzhalter, können Sie FDF-Daten importieren, anstatt jedes Feld einzeln auszufüllen. Alternativ können Sie PdfDocument.FlattenControls verwenden, um alle Felder gleichzeitig zu reduzieren.

PDFs aus statischen Vorlagen ohne Formulare erstellen

Wenn Ihre Vorlage keine Formularfelder enthält, zeichnen Sie Namen und andere Daten direkt auf die Seitenfläche. Statische PDF-Vorlagen enthalten üblicherweise feste visuelle Platzhalter wie Text, Bilder oder leere Bereiche. Um aus der Vorlage ein PDF zu erstellen, müssen Sie diese leeren Bereiche füllen und Platzhaltertext und -bilder programmatisch ersetzen.

Leere Flächen

Nutzen Sie die Canvas API, um Text und Bilder in leeren Bereichen zu platzieren. In einfachen Fällen, in denen nur geringfügige Änderungen wie das Hinzufügen eines Namens und eines Fotos erforderlich sind, eignet sich diese Methode gut. Sie müssen die Koordinaten und die Größe der Bereiche kennen. Um den Text korrekt zu positionieren, sollten Sie ihn gegebenenfalls zunächst ausmessen und anschließend entsprechend ausrichten.

Das Arbeiten mit Texten variabler Länge oder mehrzeiligen Texten ist etwas anspruchsvoller, aber dennoch möglich. Durch die Kombination von DrawText, DrawString und den Methoden zum Ausmessen von Text können Sie Zeilen nach Bedarf umbrechen und positionieren. Enthält Ihre Vorlage mehr als einige solcher Bereiche, sollten Sie eine alternative Methode in Betracht ziehen, beispielsweise die Generierung von PDFs mit der Layout API.

Platzhaltertext

Docotic.Pdf bietet auch Methoden zum Suchen und Ersetzen von Text. Die Verwendung der Textsuche als Vorlage ist jedoch meist nicht einfacher als die Arbeit mit leeren Platzhalterbereichen. Bevor Sie neue Inhalte einfügen, müssen Sie das exakte Textfragment finden und es sauber entfernen.

Platzhalterbilder

Statische Vorlagen können Platzhalterbilder für Benutzeravatare oder Produktfotos enthalten. Um ein Platzhalterbild zu finden, durchlaufen Sie die auf jeder Seite verwendeten Bilder. Für jedes Bild können Sie dessen sichtbare Größe und Position ermitteln. Um den Platzhalter zu ersetzen, verwenden Sie PdfImage.ReplaceWith.

using var pdf = new PdfDocument("invoice-template.pdf");
var paintedImages = pdf.Pages[0].GetPaintedImages();

var placeholder = paintedImages.First();
placeholder.Image.ReplaceWith("company-logo.jpg");

pdf.Save($"invoice.pdf");

Eine weitere Möglichkeit besteht darin, ein neues Bild über den Bereich zu zeichnen, der vom Platzhalterbild eingenommen wird. Dies führt jedoch in der Regel ohne triftigen Grund zu einer Vergrößerung der resultierenden PDF-Datei.

Platzhalter für einfachen Austausch entwerfen

Bei statischen Vorlagen ist es hilfreich, das Layout mit klar definierten Bereichen für Text und Bilder zu gestalten. Lassen Sie ausreichend Abstand um Bereiche, die Inhalte variabler Länge enthalten, und verwenden Sie neutrale Platzhalterbilder, deren Seitenverhältnis den später einzufügenden Bildern entspricht.

Wenn Ihre Vorlage Platzhaltertext verwendet, den Sie ersetzen möchten, können Sie den Workflow vereinfachen, indem Sie Textfelder anstelle von reinem Text verwenden. Fügen Sie der Vorlage ein schreibgeschütztes, rahmenloses Textfeld hinzu und platzieren Sie den Platzhaltertext darin. Öffnen Sie beim Generieren der endgültigen PDF-Datei die Vorlage, suchen Sie das Textfeld anhand seines Namens und weisen Sie ihm den neuen Wert direkt mit box.Text = "neuer Text"; zu. Reduzieren Sie anschließend die Spaltenbreite des Textfelds, um weitere Bearbeitungen zu verhindern.

Hinzufügen interaktiver Elemente

Interaktive Funktionen verwandeln ein statisches PDF in ein dynamisches, benutzerfreundliches Dokument mit Anmerkungen und Formatierungen. Aktionen und JavaScript ermöglichen die Automatisierung direkt im PDF.

Anmerkungen

Anmerkungen sind Objekte, die einer Seite hinzugefügt werden und Kommentare, Hervorhebungen, Dateianhänge und andere interaktive Elemente darstellen. Sie sind im Seiteninhalt sichtbar und unterstützen Prüfprozesse und die Zusammenarbeit.

Das folgende C#-Beispiel zeigt, wie Sie mit Docotic.Pdf Textanmerkungen (auch Haftnotizen genannt) zu einer PDF-Seite hinzufügen.

using var pdf = new PdfDocument("example.pdf");
var page = pdf.Pages[0];

var textAnnot = page.AddTextAnnotation(new PdfPoint(50, 100), "Reviewer comment");
textAnnot.Contents = "Please check the figures on this page.";

pdf.Save("text-annotation.pdf");

Das nächste Beispiel zeigt, wie man Text und andere Inhalte hervorhebt, um die Aufmerksamkeit auf wichtige Teile eines Dokuments zu lenken.

using var pdf = new PdfDocument("example.pdf");
var page = pdf.Pages[0];

var color = new PdfRgbColor(255, 255, 120);
var annotationText = "Please confirm this part.";
var bounds = new PdfRectangle(50, 250, 120, 40);
page.AddHighlightAnnotation(annotationText, bounds, color);

pdf.Save("highlight-annotation.pdf");

Links

PDF-Standards definieren verschiedene Arten von PDF-Links. Die wichtigsten und am weitesten verbreiteten sind interne Links und Hyperlinks.

Interne Links, auch „GoTo“-Aktionen genannt, ermöglichen das Springen zu einer Seite oder einem benannten Ziel innerhalb desselben PDFs. Sie sind nützlich für Querverweise und die interne Navigation.

Hier ist C#-Code, der einen Link von der ersten Seite zur Seite mit dem Index 5 erstellt:

using var pdf = new PdfDocument();
var page = pdf.Pages[0];

int targetPageIndex = 5;
for (int i = 0; i < targetPageIndex; i++)
    pdf.AddPage();

var rect = new PdfRectangle(50, 50, 100, 40);
page.Canvas.DrawRectangle(rect);
page.AddLinkToPage(rect, targetPageIndex);

pdf.Pages[targetPageIndex].Canvas.DrawString(50, 50, "Glad to have you here.");

pdf.Save("link-to-page.pdf");

Die Layout-API bietet eine weitere Möglichkeit, interne Links zu erstellen, die keine absolute Positionierung erfordert.

Externe Links, auch URI-Aktionen genannt, öffnen eine Web-URL. Sie können einen Hyperlink zu einer PDF-Seite hinzufügen, indem Sie die Methode PdfPage.AddHyperlink verwenden. Ansonsten ist die Vorgehensweise dieselbe wie bei internen Links.

Lesezeichen

Lesezeichen, auch Gliederungen genannt, sind spezielle Verknüpfungen, die Lesern helfen, schnell zu bestimmten Abschnitten oder Seiten zu navigieren. Beim Klicken auf ein Lesezeichen springt die Anwendung direkt zum entsprechenden Abschnitt des Dokuments.

Gliederungen erscheinen im Lesezeichenbereich der Anwendung und bieten eine hierarchische Navigationsstruktur, ähnlich einem Inhaltsverzeichnis in einem Buch, jedoch interaktiv. PDF-Gliederungen können Haupt- und Unterlesezeichen enthalten, was die Strukturierung großer Dokumente erleichtert.

Das folgende Beispiel zeigt, wie man mit C# und Docotic.Pdf Lesezeichen in PDFs erstellt. Der Code erzeugt drei Hauptlesezeichen. Das zweite Lesezeichen enthält ein Unterlesezeichen.

using var pdf = new PdfDocument();

for (int i = 0; i < 5; i++)
{
    var page = i == 0 ? pdf.Pages[0] : pdf.AddPage();

    var canvas = page.Canvas;
    canvas.FontSize = 14;
    canvas.DrawString(50, 50, $"Page {i + 1}");
}

var root = pdf.OutlineRoot;
root.AddChild("Getting Started", 1);

var child = root.AddChild("Things You Can Do", 2);
child.AddChild("Making Quick Improvements", 3);

root.AddChild("Keeping Everything Running Smoothly", 4);

pdf.PageMode = PdfPageMode.UseOutlines;

pdf.Save("bookmarks.pdf");

Lesezeichen unterscheiden sich vom Inhaltsverzeichnis eines gedruckten Buches oder einer PDF-Datei. Sie können ein Inhaltsverzeichnis programmatisch erstellen, indem Sie Überschriften analysieren und Einträge mit Seitenzahlen versehen.

Einen alternativen Ansatz zur Erstellung eines Inhaltsverzeichnisses mithilfe der Layout-API finden Sie im zugehörigen Code in unserem Beispiel-Repository.

PDF-Skripterstellung

JavaScript-Aktionen gehören zu den leistungsstärksten interaktiven Funktionen. PDF-JavaScript ist eine Teilmenge von JavaScript, die Dokument- und Viewer-APIs bereitstellt. Es wird für Formularvalidierung, Berechnungen, Benutzeroberflächendialoge und kleinere Automatisierungsaufgaben verwendet.

Sie können Skripte an Anmerkungen, Lesezeichen, Formularsteuerelemente oder Öffnungsaktionen anhängen. Mit Docotic.Pdf können Sie JavaScript-Code in ein PDF einbetten. Der Code kann Formulareingaben validieren, Werte berechnen, Felder ein- oder ausblenden oder Viewer-Interaktionen durchführen.

Die Sammlung gemeinsam genutzter JavaScript-Skripte enthält Skripte, die auf Dokumentebene gespeichert sind. Diese Skripte können von mehreren Aktionen wiederverwendet werden. Gemeinsam genutzte Skripte eignen sich also für Hilfsfunktionen und gemeinsame Logik. Sie tragen dazu bei, Redundanz zu vermeiden und die Wartung zu vereinfachen.

Der folgende Code definiert ein gemeinsam genutztes Skript, das eine Warnmeldung im PDF-Viewer anzeigt, und zeigt anschließend, wie dieses Skript durch Zuweisung zur Klickaktion der Schaltfläche ausgelöst wird.

using var pdf = new PdfDocument();

pdf.SharedScripts.Add(
    pdf.CreateJavaScriptAction("function messageBox(message) { app.alert(message,3); }")
);

var button = pdf.Pages[0].AddButton(50, 50, 100, 40);
button.Text = "Click me";
button.OnMouseUp = pdf.CreateJavaScriptAction("messageBox('Hello, dear!');");

pdf.Save("shared-javascript.pdf");

Das Skript im Beispiel ist einfach, aber Sie können JavaScript-Aktionen beliebiger Komplexität erstellen. Die Adobe JavaScript API-Referenz bietet zahlreiche Methoden, die Sie verwenden können. Beachten Sie, dass Nicht-Adobe-Viewer in der Regel nur eine Teilmenge der API unterstützen.

Offene Aktionen

Eine Öffnungsaktion ist eine Aktion, die der PDF-Viewer beim Öffnen des Dokuments ausführt. Typische Anwendungsfälle sind das Öffnen auf einer bestimmten Seite, das Ausführen einer JavaScript-Initialisierungsroutine oder das Festlegen von Viewer-Einstellungen. Es gibt keine Einschränkungen hinsichtlich der Art der Öffnungsaktion.

Das folgende Beispiel zeigt, wie eine „Gehe zu“-Öffnungsaktion erstellt wird. Der Code fügt Text auf der zweiten Seite hinzu und legt eine Öffnungsaktion fest, die bewirkt, dass der Viewer beim Öffnen der PDF-Datei automatisch zu dieser Seite navigiert.

using var pdf = new PdfDocument();

var canvas = pdf.AddPage().Canvas;
canvas.FontSize = 14;

var message =
    "If you see this immediately after opening the file, " +
    "your PDF viewer supports open actions.";
var options = new PdfTextDrawingOptions(new PdfRectangle(100, 100, 100, 150));
canvas.DrawText(message, options);

pdf.OnOpenDocument = pdf.CreateGoToPageAction(1, 0);

pdf.Save("open-action.pdf");

Beachten Sie, dass nicht alle PDF-Viewer JavaScript-Öffnungsaktionen ausführen. Manche ignorieren sie oder fragen den Benutzer vorher. Einige Viewer blockieren Öffnungsaktionen vollständig.

Um zu prüfen, ob ein PDF eine Öffnungsaktion enthält, laden Sie es in ein PdfDocument-Objekt und untersuchen Sie die OnOpenDocument-Eigenschaft. Ist diese Eigenschaft null, ist für das Dokument keine Öffnungsaktion definiert.

Anwendung von Verschlüsselung und digitalen Signaturen

Verschlüsselung und digitale Signaturen schützen Ihre PDFs auf zwei sich ergänzende Arten. Die Verschlüsselung regelt, wer ein Dokument öffnen und bearbeiten darf, während Signaturen den Ersteller bzw. Genehmiger der Datei bestätigen und ihre Unversehrtheit gewährleisten.

Mit Passwortschutz legen Sie Zugriffsregeln bereits bei der Erstellung fest. Sie können ein Öffnungspasswort vergeben, um die Ansicht einzuschränken, und ein Besitzerpasswort, um Berechtigungen wie Drucken, Kopieren, Bearbeiten oder Ausfüllen von Formularen zu definieren. Die Zertifikatsverschlüsselung bietet einen stärkeren, empfängerspezifischen Schutz und eignet sich besonders für die Verteilung vertraulicher PDFs an mehrere Personen ohne gemeinsames Passwort. Weitere Informationen finden Sie im Artikel zum Thema PDF-Verschlüsselung mit Passwörtern und Zertifikaten.

Digitale Signaturen erhöhen Authentizität und Integrität bereits bei der Erstellung. Docotic.Pdf kann PDFs signieren mit Zertifikaten aus Dateien, dem Windows-Zertifikatsspeicher, Hardware-Tokens, HSMs oder Cloud-Key-Diensten. Sie können Zeitstempel und Langzeitvalidierungsdaten einfügen, sodass Signaturen auch lange nach der Dokumentenerstellung überprüfbar bleiben. Externe Signatur-Workflows, einschließlich PKCS#11 und Cloud-KMS, werden ebenfalls unterstützt.

PDF-Metadaten festlegen

PDF-Metadaten sind beschreibende Informationen, die in ein Dokument eingebettet sind, wie z. B. Titel, Autor, Betreff, Schlüsselwörter, Erstellungsdatum und ähnliche Felder. Sie helfen Software, Suchmaschinen und Dokumentenmanagementsystemen, den Inhalt einer Datei zu verstehen, ohne sie öffnen zu müssen.

Ein PDF-Dokument kann Metadaten in zwei parallel existierenden Systemen enthalten:

• XMP-Metadaten
• Dokumentinformationswörterbuch (Info-Wörterbuch)

XMP ist das umfangreichere, strukturierte und standardisierte Format zum Einbetten beschreibender Metadaten. Das Info-Wörterbuch ist zwar einfach und weit verbreitet, aber in seinen Möglichkeiten eingeschränkt und wird im PDF 2.0-Standard (ISO 32000-2) zugunsten von XMP-Metadaten als veraltet eingestuft. Docotic.Pdf kann beide Systeme lesen und schreiben und bietet eine Hilfsmethode, um sie synchron zu halten.

Docotic.Pdf aktualisiert einige Metadaten automatisch vor dem Speichern einer PDF-Datei. Beispielsweise setzt die Bibliothek standardmäßig die Werte für Produzent und Ersteller. Verwenden Sie die Speicheroptionen, um dieses Verhalten zu ändern und explizit festgelegte Metadatenwerte beizubehalten.

XMP-Metadaten

Verwenden Sie die Eigenschaft PdfDocument.Metadata, um auf XMP-Metadaten in einem PDF zuzugreifen und diese zu ändern. Mit dieser Eigenschaft können Sie mit bekannten Schemas wie XMP Core, Dublin Core und dem PDF-Schema arbeiten sowie Ihre eigenen benutzerdefinierten Metadaten verwalten.

using var pdf = new PdfDocument();
var xmp = pdf.Metadata;

xmp.Pdf.Creator = new XmpString("Second-line authoring terminal");
xmp.Pdf.Title = new XmpString("Quarterly Report");

var creators = new XmpArray(XmpArrayType.Ordered);
creators.Values.Add(new XmpString("Second-line authoring terminal"));
creators.Values.Add(new XmpString("Assistive authoring terminal"));
xmp.DublinCore.Creators = creators;

var descriptions = new XmpArray(XmpArrayType.Alternative);
descriptions.Values.Add(new XmpLanguageAlternative("x-default", "Quarterly Report"));
descriptions.Values.Add(new XmpLanguageAlternative("fr", "Rapport trimestriel"));
descriptions.Values.Add(new XmpLanguageAlternative("de", "Quartalsbericht"));
xmp.DublinCore.Descriptions = descriptions;

var author1 = new XmpString("First Author");
author1.Qualifiers.Add("role", "main author");

var author2 = new XmpString("Second Author");
author2.Qualifiers.Add("role", "co-author");

var authors = new XmpArray(XmpArrayType.Unordered);
authors.Values.Add(author1);
authors.Values.Add(author2);
xmp.Custom.Properties.Add("authors", authors);

pdf.Save("with-xmp-metadata.pdf");

XMP unterstützt Arrays, Strukturen und typisierte Werte und eignet sich daher gut für umfangreiche Metadaten. Der obige Code zeigt außerdem, wie anwendungsspezifische Eigenschaften im benutzerdefinierten XMP-Schema gespeichert werden.

Dokumenteninformationswörterbuch

Das Info-Wörterbuch speichert primär Textzeichenfolgen. Es ist kompakt und wird weitgehend unterstützt, hat aber Einschränkungen. Verwenden Sie das Info-Wörterbuch aus Kompatibilitätsgründen mit älteren Tools und bevorzugen Sie in anderen Fällen XMP.

Metadaten synchronisieren

Es empfiehlt sich, beide Metadatensysteme zu synchronisieren, um Inkonsistenzen zu vermeiden, die Leser und automatisierte Tools verwirren könnten.

Verwenden Sie PdfDocument.SyncMetadata, um XMP- und Info-Werte so abzugleichen, dass die entsprechenden Felder übereinstimmen. Die Methode füllt fehlende Info-Eigenschaften aus XMP und umgekehrt fehlende XMP-Felder aus Info. Setzen Sie preferXmp: true, wenn XMP Ihre maßgebliche Quelle ist, oder false, wenn das Info-Wörterbuch Vorrang haben soll.

pdf.SyncMetadata(preferXmp: true);

Detaillierte Informationen darüber, welche Eigenschaften die Methode synchronisiert, finden Sie im Abschnitt „Anmerkungen“ der Dokumentation zu SyncMetadata.

Seitenbezeichnungen und Anzeigeeinstellungen konfigurieren

Eine neu erstellte PDF-Datei profitiert von einer expliziten Seitennummerierung, präzisen Einstellungen des Anzeigeprogramms und einem Seitenlayout, das den Dokumentinhalt optimal präsentiert. Diese Einstellungen beeinflussen, wie Leser die Datei sehen und darin navigieren.

Seitenetiketten

Seitenbezeichnungen sind Metadaten, die PDF-Readern mitteilen, welche Bezeichnung für jede Seite angezeigt werden soll. Verwenden Sie sie, wenn die sichtbare Seitennummerierung vom physischen Seitenindex abweichen soll. Zum Beispiel, wenn Sie für das Vorwort „i, ii, iii“ und für den Haupttext in Ihrer PDF-Datei „1, 2, 3“ verwenden möchten.

Der folgende C#-Code zeigt, wie Sie PDF-Seiten mit römischen Kleinbuchstaben für die ersten drei Seiten und arabischen Ziffern ab 1 für die restlichen Seiten beschriften.

using var pdf = new PdfDocument();

for (int i = 0; i < 8; i++)
    pdf.AddPage();

pdf.PageLabels.AddRange(0, 2, PdfPageNumberingStyle.LowercaseRoman);
pdf.PageLabels.AddRange(3, PdfPageNumberingStyle.DecimalArabic);

pdf.Save("with-page-labels.pdf");

PDF-Viewer-Einstellungen

Die PDF-Anzeigeeinstellungen sind Empfehlungen, die im Dokument eingebettet sind und die Darstellung im Anzeigeprogramm beeinflussen. Sie können beispielsweise festlegen, dass Symbolleisten ausgeblendet, das Fenster zentriert oder an die Seitengröße angepasst werden soll. Die Anzeigeeinstellungen ergänzen die Einstellungen für Seitenlayout und Öffnungsaktion.

So ändern Sie die PDF-Anzeigeeinstellungen mit Docotic.Pdf:

using var pdf = new PdfDocument();

pdf.ViewerPreferences.DisplayTitle = false;
pdf.ViewerPreferences.FitWindow = true;
pdf.ViewerPreferences.HideToolBar = true;
pdf.ViewerPreferences.HideMenuBar = true;
pdf.ViewerPreferences.HideWindowUI = true;
pdf.ViewerPreferences.CenterWindow = true;

pdf.Save("with-viewer-prefs.pdf");

Bitte beachten Sie, dass Adobe Acrobat und andere Viewer diese Einstellungen je nach Konfiguration möglicherweise ignorieren.

Seitenlayout und Seitenmodus

Das Seitenlayout bestimmt, wie die Seiten beim Öffnen des Dokuments angeordnet werden: als Einzelseite, einspaltig fortlaufend oder als Doppelseite. Der Seitenmodus steuert, welche Benutzeroberflächenelemente beim Öffnen sichtbar sind: Lesezeichen/Gliederungen, Anhänge, Miniaturansichten oder keine.

So legen Sie fest, dass die erstellte PDF-Datei als Doppelseite angezeigt wird, wobei die linke Seite zuerst erscheint und die Miniaturansichten beim Öffnen sichtbar sind:

using var pdf = new PdfDocument();

for (int i = 0; i < 7; i++)
{
    var page = i > 0 ? pdf.AddPage() : pdf.Pages[0];
    page.Canvas.FontSize = 36;
    page.Canvas.DrawString(100, 100, $"Page {i + 1}");
}

pdf.PageLayout = PdfPageLayout.TwoPageLeft;
pdf.PageMode = PdfPageMode.UseThumbs;

pdf.Save("with-layout-and-mode.pdf");

PDFs speichern

Docotic.Pdf kann aus demselben Dokument, das Sie erstellt oder bearbeitet haben, verschiedene PDF-Dateien oder -Streams erzeugen. Diese Ausgaben können unterschiedlichen PDF-Formaten entsprechen, sich in ihrer Byte-Länge unterscheiden und unterschiedlich viel Speicherplatz benötigen.

Die Art und Weise, wie die Bibliothek die Bytes eines PDFs erzeugt, hängt von den Speicheroptionen ab. Wenn Sie keine Speicheroptionen explizit angeben, verwenden die Methoden Save, SignAndSave und TimestampAndSave eines PdfDocument-Objekts Standardeinstellungen. Diese Standardwerte sind sorgfältig gewählt und funktionieren in den meisten Fällen gut, müssen aber gegebenenfalls angepasst werden.

Detaillierte Informationen zu den verfügbaren Optionen und ihren Standardwerten finden Sie in der Dokumentation der Klasse PdfSaveOptions. Die folgenden Abschnitte heben einige der wichtigsten Optionen hervor und geben praktische Empfehlungen.

PDF-Version

Docotic.Pdf verwendet standardmäßig Objektströme, um eine bessere Komprimierung der erzeugten Dateien zu erzielen. Daher erstellt die Bibliothek standardmäßig PDF-1.5-Dateien und -Streams.

PDF 1.5 erfordert Adobe Reader 6 (veröffentlicht 2003) oder neuer, um die erstellten Dokumente anzuzeigen. Dies ist in der Regel kein Problem, es sei denn, Sie müssen ältere Tools, Viewer oder eingebettete Geräte unterstützen, die nur ältere PDF-Versionen akzeptieren.

So speichern Sie mit einer älteren PDF-Datei:

using var pdf = new PdfDocument();

var options = new PdfSaveOptions
{
    Version = PdfVersion.Pdf14,
    UseObjectStreams = false,
};
pdf.Save("version-1.4.pdf", options);

Um mit PDF 1.4 zu speichern, müssen Objektströme deaktiviert sein. Die Bibliothek verwendet keine ältere Version, wenn das Dokument Funktionen enthält, die in späteren Versionen eingeführt wurden.

Dateigrößenreduzierung

Mehrere Speicheroptionen, die auf true gesetzt sind, bewirken, dass Docotic.Pdf kleinere Dateien (byte-weise) erzeugt: RemoveUnusedObjects, OptimizeIndirectObjects, WriteWithoutFormatting und UseObjectStreams.

So erzeugen Sie PDFs ohne nicht referenzierte Objekte und überflüssige Leerzeichen, wobei die Daten platzsparend in Objektströmen gepackt sind:

using var pdf = new PdfDocument();

var options = new PdfSaveOptions
{
    UseObjectStreams = true,
    RemoveUnusedObjects = true,
    OptimizeIndirectObjects = true,
    WriteWithoutFormatting = true,
};
pdf.Save("optimized.pdf", options);

Diese Optionen sind am effektivsten, wenn die PDF-Datei vollständig neu geschrieben wird. Bei einer inkrementellen Speicherung gelten sie nur für die neu hinzugefügte Revision und können frühere Teile der Datei nicht bereinigen oder optimieren.

Inkrementelle Aktualisierungen

Docotic.Pdf kann PDFs inkrementell aktualisieren. Wenn WriteIncrementally auf true gesetzt ist, fügt die Bibliothek die Änderungen an die bestehende Datei an, anstatt sie neu zu schreiben. Die vorherigen Querverweise und Objektdaten bleiben erhalten. Die angehängten Daten werden als inkrementelle Aktualisierung bezeichnet, und die aktuelle Aktualisierung bildet zusammen mit allen vorherigen Aktualisierungen eine neue Revision der Datei.

Inkrementelle Aktualisierungen sind für neu erstellte Dokumente nicht möglich, da keine vorherige Revision vorhanden ist, an die angehängt werden könnte. Die Bibliothek ignoriert diese Option für neue Dokumente und schreibt sie im nicht-inkrementellen Modus.

Wann inkrementelle Aktualisierungen erforderlich sind

Beim Hinzufügen einer neuen digitalen Signatur zu einem Dokument, das bereits Signaturen enthält, muss die Datei inkrementell gespeichert werden. Dasselbe gilt für die Aktualisierung einer zuvor signierten Datei mit neuen Anmerkungen oder Formulardaten. Das Überschreiben der gesamten Datei würde in diesen Fällen die vorhandenen Signaturen ungültig machen.

Gleichzeitig empfiehlt es sich, vor dem Anwenden der ersten digitalen Signatur eine vollständige (nicht-inkrementelle) Speicherung durchzuführen, damit die signierte Ausgangsdatei eine saubere, vollständig überschriebene Datei ist. Das Signieren eines Dokuments, das in früheren Versionen strukturelle Probleme aufweist, kann zu unerwarteten Problemen bei der Signaturvalidierung führen.

Inkrementelle Anhänge sind auch in Workflows erforderlich, die eine nachvollziehbare Revisionshistorie benötigen oder die Speicherung von Dokumenten nur mit Anhängen erzwingen.

Vorteile der Verwendung inkrementeller Updates

Inkrementelle Aktualisierungen ermöglichen mehrere Signaturen für dieselbe Datei und erlauben begrenzte Änderungen nach der Signatur, wie z. B. das Ausfüllen von Formularfeldern, ohne bestehende Signaturen zu beeinträchtigen.

Dieses Verfahren ermöglicht zudem schnellere Speichervorgänge bei kleineren Änderungen, da nur die geänderten Daten geschrieben werden. Außerdem bleibt der Revisionsverlauf des Dokuments erhalten, was für Audits und andere Compliance-relevante Arbeitsabläufe unerlässlich ist.

Zu vermeidende Probleme und Fallstricke

Inkrementelle Aktualisierungen können keine globale Komprimierung anwenden oder veraltete Objekte in der gesamten Datei entfernen, da sie nur die geänderten Objekte anhängen. Daher erzeugen sie in der Regel größere und weniger optimierte Dateien als eine vollständige Neuinstallation.

Die Dateigröße wächst mit jeder Revision, selbst wenn keine ungenutzten Objekte vorhanden sind, da alle vorherigen Revisionen in der Datei eingebettet bleiben und weiterhin Speicherplatz belegen.

Sensible oder fehlerhafte Informationen aus früheren Revisionen können wiederhergestellt werden, und bestehende PDF-Formatprobleme oder strukturelle Defekte in früheren Revisionen werden durch das Anhängen neuer Daten nicht behoben.

Schließlich haben einige Anzeigeprogramme und Verarbeitungswerkzeuge Schwierigkeiten mit PDFs mit mehreren Revisionen. Bevor Sie inkrementelle Aktualisierungen verwenden, stellen Sie sicher, dass alle Empfänger Ihrer Dokumente Dateien mit mehreren Revisionen verarbeiten können.

Testen der PDF-Ausgabe

Automatisierte PDF-Tests schützen Releases vor Fehlern in Inhalt und Layout, indem generierte PDFs mit in Ihrem Repository oder Artefaktspeicher abgelegten Baseline-PDFs verglichen werden. Baselines helfen Ihnen, versehentliche Änderungen an Text, Schriftarten, Bildern oder Layout zu erkennen und den Bedarf an manueller Qualitätssicherung bei jedem Build zu reduzieren.

Kombinieren Sie Strukturprüfungen, Textextraktion und visuelle Vergleiche für optimale Ergebnisse.

Schneller Vergleich der Ansätze

Vergleich der Dokumentenstruktur

Verwenden Sie PdfDocument.DocumentsAreEqual, um PDF-Objektgraphen, die PDF-Version und den Dokumentensicherheitsspeicher (DSS) zu vergleichen und dabei zeitabhängige Dokumenteigenschaften zu ignorieren. Die Methode ignoriert außerdem Dokumentmetadaten, Trailer-IDs und andere automatisch generierte Eigenschaften.

Diese Methode eignet sich ideal für PDF-Dokumenttest-Workflows, die sicherstellen müssen, dass keine unerwarteten Objekte hinzugefügt oder entfernt wurden. DocumentsAreEqual unterstützt Datei- und Stream-Überladungen und kann verschlüsselte PDFs vergleichen.

Ein vollständiges Beispiel, das diese Technik demonstriert, finden Sie in den Docotic.Pdf-Beispielen. Neben der Verwendung der Methode in regulären .NET-Anwendungen zeigt das Beispiel auch, wie DocumentsAreEqual in nativen AOT-Anwendungen eingesetzt wird.

PDFs anhand des extrahierten Textes überprüfen

Extrahieren Sie Text aus dem gesamten Dokument oder seitenweise und vergleichen Sie die Zeichenketten. Mithilfe von Optionen zur Textextraktion können Sie den Extraktionsprozess feinabstimmen, z. B. indem Sie den Bereich mit der Fußzeile ausschließen. Um den Vergleich zu vereinfachen, können Sie den extrahierten Text in Zeilen oder Wörter unterteilen.

Für strukturierte Prüfungen extrahieren Sie zunächst Text mit Position, Schriftart und weiteren detaillierten Informationen zu jedem Abschnitt, Wort oder Zeichen. Vergleichen Sie anschließend jedes extrahierte Element mit dem entsprechenden Referenzelement.

Visuelle Unterschiede erkennen

Beginnen Sie damit, PDF-Seiten in Bilder umzuwandeln und jedes Bild mit dem Referenzbild zu vergleichen. Verwenden Sie spezialisierte Bibliotheken wie ImageSharp.Compare oder Magick.NET, um Bildunterschiede zu erkennen.

Bevorzugen Sie einen strikten Pixel-für-Pixel-Vergleich, sodass jedes entsprechende Pixel in beiden Bildern übereinstimmen muss. Falls Ihre Anforderungen geringfügige Abweichungen beim Rendern zulassen, können Sie die Vergleichslogik anpassen, um kleinere Unterschiede zu tolerieren. Die zuverlässigsten Ergebnisse werden jedoch durch die exakte Pixelübereinstimmung erzielt.

Alternativ können Sie Hashing als schnelle Vorprüfung verwenden, um festzustellen, ob zwei Bilder wahrscheinlich identisch sind, ohne einen vollständigen Pixelvergleich durchzuführen. Berechnen Sie für jedes gerenderte Bild einen SHA-256-Hash. Stimmen die Hashes überein, sind die Bilder mit hoher Wahrscheinlichkeit identisch. Sind die Hashes unterschiedlich, führen Sie den vollständigen Pixel-für-Pixel-Vergleich durch.

Abschluss

Docotic.Pdf bietet ein umfassendes, mehrschichtiges Toolkit zum Erstellen und Bearbeiten von PDFs in .NET. Entwickler können zwischen der Low-Level-Steuerung mit der Core API, der High-Level-Dokumentgenerierung mit der Layout API oder der HTML-zu-PDF-Konvertierung für Workflows wählen, die bereits auf Webtechnologien basieren.

Die Bibliothek unterstützt außerdem bildbasierte PDFs, die vorlagenbasierte Generierung und eine Vielzahl interaktiver Funktionen wie Anmerkungen, Links, Lesezeichen, JavaScript-Aktionen und Öffnungsaktionen.

Um die Zuverlässigkeit zu gewährleisten, enthält Docotic.Pdf Methoden zum Testen der PDF-Ausgabe, sodass Änderungen in Ihrer Anwendung keine Regressionen oder unerwartete Unterschiede verursachen.