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

Übersetzt von Bit Miracle. Originalartikel von Vitaliy Shibaev

Aktualisiert am 29. Juni 2026

Dieser Artikel beschreibt verschiedene Möglichkeiten, PDF-Dokumente in .NET mithilfe der Docotic.Pdf-Bibliothek zu erstellen. Es ist 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 Ansätze zum Erstellen von PDFs mit Docotic.Pdf vor:

• Verwendung der Core API, die niedrigstufige Kontrolle über Text, Grafiken und PDF-Interna bietet. Diese Option eignet sich am besten für benutzerdefinierte Layouts, grafikintensive Dokumente und erweiterte Funktionen.
• Verwendung der High-Level Layout API, die Absätze, Tabellen, Kopf- und Fußzeilen sowie automatische Paginierung unterstützt. Diese API ist ideal, wenn Sie strukturierte Dokumente ohne manuelle Positionsberechnung erstellen möchten.
• Konvertieren von HTML in PDF mit Unterstützung für SVG und andere Webformate. Dieser Ansatz ist besonders nützlich, wenn Ihre Lösung bereits HTML-Dokumente erzeugt und Sie PDF-Versionen dieser HTML- und CSS-Dateien benötigen.
• Erstellen von PDFs aus Bildern. Diese Methode ist nützlich für gescannte Dokumente, bildbasierte Berichte, Belege und jeden Workflow, der mit Rasterbildern beginnt.
• Zusammenführen oder Aufteilen von PDFs. Dies ist eine gute Wahl für das Zusammenstellen von Berichten, die Verarbeitung von Benutzer-Uploads, das Kombinieren zusammengehöriger Dokumente und die Umstrukturierung großer PDFs.
• Erstellen von PDFs aus Vorlagen. Dieser Ansatz eignet sich gut, wenn für stapelweise erzeugte Dokumente wie Belege, Steuerformulare, Arbeitsverträge und andere wiederholbare Dokumenttypen ein konsistentes Layout erforderlich ist.

Weitere im Leitfaden behandelte Themen:

• Interaktive Funktionen wie Links und JavaScript-Aktionen
• Ansätze zum Testen der PDF-Ausgabe, um erwartete Ergebnisse sicherzustellen

Erstellen von PDFs mit der Core API

Die Core API ist die Grundlage der PDF-Erstellung in Docotic.Pdf. Sie gibt Ihnen volle, niedrigstufige Kontrolle über das Platzieren von Text, Bildern und Vektorgrafiken auf einem PDF-Canvas über seine Canvas API. Diese Zeichen-API ist eine Teilmenge der Core API und stellt die Methoden und Eigenschaften bereit, die zum Hinzufügen von Inhalten zu Seiten und anderen Objekten mit Canvas verwendet werden. Über das Rendern hinaus unterstützt die Core API auch Anmerkungen, Formularfelder, Ebenen, Lesezeichen und andere PDF-Funktionen.

Hier ist C#-Code, der ein einfaches PDF mit drei grundlegenden Operationen erstellt: Text zeichnen, ein Bild platzieren und Vektorgrafiken auf einem Seiten-Canvas 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");

Dieser Überblick stellt nur einen kleinen Teil dessen vor, was die Core API kann. Für erweiterte Themen finden Sie den ausführlichen Artikel zum Erstellen von PDFs mit der Core API. Der Artikel behandelt das Messen von Text, die Arbeit mit Farbräumen, das Anwenden von Clipping, das Füllen von Flächen mit Mustern, den Umgang mit Transparenz und weitere Funktionen.

Erstellen von PDFs mit der Layout API

Die Layout API ist eine High-Level-Engine zum Erstellen von Dokumenten, die die einfachste und effizienteste Möglichkeit bietet, komplexe, inhaltsreiche PDFs zu erzeugen.

Bei der Verwendung der API setzen Sie PDFs aus strukturellen Elementen wie Seiten, Containern, Textspans, Bildern, Tabellen, Links, Kopf- und Fußzeilen und mehr zusammen. Statt Koordinaten zu berechnen oder die Paginierung manuell zu verwalten, beschreiben Sie die Struktur des Dokuments und lassen die Layout-Engine den Rest übernehmen.

Dieses Beispiel zeigt, wie man mit der Layout API ein PDF erstellt und dabei auf deklaratives Layout statt auf manuelle Positionierung setzt.

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);
        });
    }));

Lesen Sie den ausführlichen Leitfaden, um zu erfahren, wie Sie die Layout API beim Erstellen von PDFs in .NET Anwendungen verwenden.

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

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

Die HTML-zu-PDF-API kann PDFs aus vollständigen HTML-Seiten oder HTML-Fragmenten erstellen. Sie können Inhalte aus URLs, rohen HTML-Strings und lokalen HTML-Dateien konvertieren. Die beiden letzteren Optionen erleichtern das Erzeugen von PDFs aus HTML-Vorlagen.

Hier sehen Sie ein Beispiel dafür, wie ein PDF aus einer HTML-Vorlage erzeugt wird:

public static async Task HelloHtmlTemplate()
{
    static string GetUserName()
    {
        // Durch echte Logik ersetzen: Formulareingabe, API-Aufruf, Konfiguration usw.
        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 unserem ausführlichen Überblick über HTML zu PDF.

Erstellen von PDFs aus Bildern

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

Wenn es vom PDF-Format unterstützt wird, bettet Docotic.Pdf Bilddaten unverändert ein und vermeidet so die Pixeldkodierung und erneute Kodierung, um die ursprüngliche Komprimierung zu erhalten. Die Bibliothek bewahrt 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üssen, hilft Ihnen die Layout API, Elemente mit minimalem Aufwand anzuordnen und auszurichten.

Wie man mehrere Bilder zu einem PDF zusammenführt

Mit Docotic.Pdf können Sie problemlos eine Reihe von Bildern in ein einzelnes PDF umwandeln, wobei pro Seite jeweils ein Bild platziert wird.

Das folgende Beispiel lädt Bilder aus Dateien und zeichnet jedes auf eine eigene Seite. Jedes Bild wird so skaliert, dass es auf die Seite passt, und zentriert, um ein sauberes, konsistentes Layout zu erzielen.

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);
}

Verarbeitung mehrseitiger TIFF- und GIF-Bilder

Docotic.Pdf unterstützt mehrseitige TIFF- und GIF-Dateien vollständig. Wenn Sie Bilder zu einem PDF hinzufügen, verwenden Sie die Methode OpenImage statt CreateImage, falls eines der Bilder mehrere Seiten enthalten kann.

Der folgende Code zeigt, wie TIFF in PDF konvertiert wird, und 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);
}

Sie können denselben Ansatz verwenden, um GIF in PDF zu konvertieren. Er gilt auch für andere Bildformate, ist jedoch für Formate mit nur einem Frame aufwendiger als nötig.

Zusammenführen und Aufteilen von PDFs

Als voll ausgestattete .NET-Bibliothek kann Docotic.Pdf neue PDFs erstellen, indem Seiten aus vorhandenen Dokumenten zusammengeführt, extrahiert und neu geordnet werden.

Wenn Sie PDFs zusammenführen, fügt die Bibliothek nicht nur Seiten aus einem anderen Dokument hinzu, sondern hängt auch Ebenen, Lesezeichen, Seitenbeschriftungen, gemeinsames JavaScript, Ziele (Linkziele) und eingebettete Dateien an. Weitere Details und Hinweise zur Verringerung der Größe zusammengeführter PDFs finden Sie im Artikel zum Zusammenführen von PDFs.

Digital signierte PDFs können nicht zusammengeführt werden, ohne ihre vorhandenen Signaturen ungültig zu machen. Um Signaturen zu erhalten, erstellen Sie ein PDF-Portfolio statt Dokumente anzuhängen. Eine andere Möglichkeit besteht darin, zuerst die PDFs zusammenzuführen und dann dem kombinierten Dokument eine neue digitale Signatur anzuwenden.

Docotic.Pdf ermöglicht Ihnen außerdem, Seiten in neue Dokumente zu kopieren und zu extrahieren. Alle mit den kopierten Seiten verbundenen Inhalte bleiben erhalten, einschließlich Anmerkungen, Formularsteuerelemente, strukturierte Inhalte, Ebenen und andere zugehörige Daten. Praktische Beispiele finden Sie im Artikel zum Aufteilen von PDFs in .NET. Dort wird auch erläutert, wie Seiten extrahiert oder entfernt werden.

Arbeiten mit PDF-Vorlagen

PDF-Vorlagen sind vorgefertigte PDF-Dateien, die als Basisstruktur für neue Dokumente dienen. Sie sind nützlich, wenn Sie PDFs mit einem konsistenten Layout erstellen und gleichzeitig unterschiedliche Daten einfügen müssen. Wenn Sie das visuelle Design von den Daten selbst trennen möchten, sind PDF-Vorlagen ebenfalls eine gute Wahl.

Vorlagen können formularbasierte PDFs oder statische PDFs ohne Formulare sein. Beide Typen dienen demselben Zweck. Darüber hinaus enthalten formularbasierte Vorlagen interaktive Elemente, die, sofern sie nicht flattened werden, Informationen von Benutzern erfassen können.

Erstellen von PDFs aus formularbasierten Vorlagen

Formularbasierte Vorlagen enthalten normalerweise AcroForms, den standardisierten und weit verbreiteten Typ interaktiver PDF-Formulare. Um aus einer solchen Vorlage ein PDF zu erzeugen, müssen Sie typischerweise:

• jedes Platzhalterfeld ausfüllen
• die Felder flattenen, um weitere Bearbeitung zu verhindern
• das Ergebnis als neues PDF speichern

Hier ist C#-Code, der ein Platzhalter-Textfeld anhand seines Namens findet, ihm einen Wert zuweist, das Feld flattenen und das Ergebnis speichert, wodurch ein PDF aus der Vorlage erstellt wird:

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");

Wenn Ihre Vorlage viele Platzhalter enthält, können Sie FDF-Daten importieren, statt jedes Feld einzeln auszufüllen. Sie können auch PdfDocument.FlattenControls verwenden, um alle Felder auf einmal zu flattenen.

Erstellen von PDFs aus statischen Vorlagen ohne Formulare

Wenn Ihre Vorlage keine Formularfelder enthält, zeichnen Sie Namen und andere Daten direkt auf den Seiten-Canvas. Statische PDF-Vorlagen enthalten üblicherweise feste visuelle Platzhalter wie Text, Bilder oder leere Bereiche. Um aus der Vorlage ein PDF zu erzeugen, müssen Sie diese leeren Bereiche füllen und Platzhaltertexte und -bilder programmgesteuert ersetzen.

Leere Bereiche

Verwenden Sie die Canvas API, um Text und Bilder in leere Bereiche zu platzieren. In einfachen Fällen, wenn nur kleinere Änderungen wie das Hinzufügen eines Namens und eines Fotos erforderlich sind, funktioniert dieser Ansatz gut. Sie müssen die Koordinaten und die Größe der Bereiche kennen, und um Text korrekt zu positionieren, müssen Sie ihn möglicherweise zunächst messen und dann entsprechend ausrichten.

Mit variabellangem oder mehrzeiligem Text zu arbeiten ist anspruchsvoller, aber dennoch machbar. Durch die Kombination von DrawText, DrawString und den Methoden zum Messen von Text können Sie Zeilen nach Bedarf umbrechen und positionieren. Wenn Ihre Vorlage mehr als nur ein paar solcher Bereiche enthält, sollten Sie eine Alternative wie das Erstellen von PDFs mit der Layout API in Betracht ziehen.

Platzhaltertext

Docotic.Pdf bietet außerdem Methoden zum Suchen und Ersetzen von Text. Die Verwendung der Textsuche als Vorlagenmechanismus ist jedoch normalerweise nicht einfacher als die Arbeit mit leeren Platzhalterbereichen. Bevor Sie neuen Inhalt einfügen, müssen Sie den exakten Textausschnitt lokalisieren und sauber entfernen.

Platzhalterbilder

Statische Vorlagen können Platzhalterbilder für Benutzer-Avatare oder Produktfotos enthalten. Um ein Platzhalterbild zu finden, enumerieren Sie die Sammlung der auf jeder Seite gezeichneten Bilder. Für jedes gezeichnete Bild können Sie seine 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 andere Möglichkeit besteht darin, ein neues Bild über den vom Platzhalterbild belegten Bereich zu zeichnen, aber dies erhöht in der Regel ohne guten Grund die Größe des resultierenden PDFs.

Platzhalter für einfachen Austausch gestalten

Bei statischen Vorlagen ist es hilfreich, das Layout mit vorhersehbaren, klar definierten Bereichen für Text und Bilder zu gestalten. Lassen Sie genügend Innenabstand um Bereiche, die variabellangen Inhalt enthalten werden, und verwenden Sie neutrale Platzhalterbilder, die den Seitenverhältnissen entsprechen, die Sie später einfügen möchten.

Wenn Ihre Vorlage Platzhaltertext verwendet, den Sie ersetzen möchten, können Sie den Workflow vereinfachen, indem Sie Textfelder statt Rohtext verwenden. Fügen Sie der Vorlage ein schreibgeschütztes Textfeld ohne Rahmen hinzu und platzieren Sie den Platzhaltertext darin. Wenn Sie das endgültige PDF erzeugen, öffnen Sie die Vorlage, lokalisieren Sie das Textfeld anhand seines Namens und weisen Sie den neuen Wert direkt mit box.Text = "new text"; zu. Flattenen Sie anschließend das Textfeld, um weitere Änderungen zu verhindern.

Hinzufügen interaktiver Elemente

Interaktive Funktionen verwandeln ein statisches PDF in ein dynamisches, leicht navigierbares Dokument mit Anmerkungen und Markup. Aktionen und JavaScript ermöglichen Automatisierung direkt innerhalb des PDFs.

Anmerkungen

Anmerkungen sind Objekte, die an eine Seite angehängt sind und Kommentare, Hervorhebungen, Dateianhänge und andere interaktive Widgets repräsentieren. Sie sind im Seiteninhalt sichtbar und unterstützen Review-Workflows und Zusammenarbeit.

Das folgende C#-Beispiel zeigt, wie man mit Docotic.Pdf Textanmerkungen, auch als Haftnotizen bekannt, zu einer PDF-Seite hinzufügt.

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 mehrere Arten von PDF-Links. Die wichtigsten und am häufigsten verwendeten sind interne Links und Hyperlinks.

Interne Links, auch GoTo-Aktionen genannt, ermöglichen Sprünge zu einer Seite oder einem benannten Ziel innerhalb desselben PDFs. Sie sind nützlich für Querverweise und 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 einen anderen Weg, interne Links zu erstellen, der keine absolute Positionierung erfordert.

Externe Links, auch URI-Aktionen genannt, öffnen eine Web-URL. Sie können mit der Methode PdfPage.AddHyperlink einen Hyperlink zu einer PDF-Seite hinzufügen. Ansonsten ist der Ansatz derselbe wie bei internen Links.

Lesezeichen

Lesezeichen, auch Gliederungen genannt, sind spezielle Verknüpfungen oder Links, die Lesern helfen, schnell zu bestimmten Abschnitten oder Seiten zu navigieren. Wenn der Leser auf ein Lesezeichen klickt, springt die Viewer-Anwendung zum vorgesehenen Teil des Dokuments.

Gliederungen erscheinen im Lesezeichenbereich des Viewers und bieten einen hierarchischen Navigationsbaum, ähnlich einem Inhaltsverzeichnis in einem Buch, aber interaktiv. PDF-Gliederungen können Haupt- und verschachtelte Lesezeichen 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 Lesezeichen auf oberster Ebene. Das zweite Lesezeichen enthält ein verschachteltes Lesezeichen.

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, das Sie möglicherweise auf den Seiten eines physischen Buches gedruckt oder in einem PDF angezeigt finden. Sie können ein Inhaltsverzeichnis programmgesteuert erstellen, indem Sie Überschriften messen und Einträge mit Seitenzahlen schreiben.

Um einen alternativen Ansatz zum Erstellen eines Inhaltsverzeichnisses mit der Layout API zu sehen, werfen Sie einen Blick auf den zugehörigen Code in unserem Beispielrepository.

PDF-Scripting

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 kleine 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 anzeigen oder ausblenden oder Interaktionen im Viewer ausführen.

Die Sammlung gemeinsam genutzter JavaScript-Skripte enthält Skripte, die auf Dokumentebene gespeichert sind. Diese Skripte können von mehreren Aktionen wiederverwendet werden. Anders ausgedrückt sind gemeinsam genutzte Skripte nützlich für Hilfsfunktionen und gemeinsame Logik. Sie helfen, Duplikate zu reduzieren und die Wartung zu vereinfachen.

Der folgende Code definiert ein gemeinsam genutztes Skript, das im PDF-Viewer eine Warnmeldung anzeigt, und zeigt dann, wie dieses Skript ausgelöst wird, indem es der Klickaktion der Schaltfläche zugewiesen 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 erstellen beliebiger Komplexität. Die Referenz der Adobe JavaScript API bietet viele Methoden, die Sie verwenden können. Beachten Sie, dass Viewer ohne Adobe-Unterstützung normalerweise nur eine Teilmenge der API unterstützen.

Öffnungsaktionen

Eine Öffnungsaktion ist eine Aktion, die der PDF-Viewer ausführt, wenn das Dokument geöffnet wird. 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 des Typs der Öffnungsaktion.

Das folgende Beispiel zeigt, wie man eine GoTo-Öffnungsaktion erstellt. Der Code fügt der zweiten Seite Text hinzu und setzt eine Öffnungsaktion, die den Viewer beim Öffnen des PDFs 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 Viewer JavaScript-Öffnungsaktionen ausführen. Einige ignorieren sie oder fragen den Benutzer zuerst. Einige Viewer blockieren Öffnungsaktionen vollständig.

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

Anwenden von Verschlüsselung und digitalen Signaturen

Verschlüsselung und digitale Signaturen adressieren zwei komplementäre Aspekte der Absicherung der PDFs, die Sie erstellen. Verschlüsselung steuert, wer ein Dokument öffnen kann und was damit gemacht werden darf, während Signaturen beweisen, wer die Datei erstellt oder genehmigt hat, und bestätigen, dass sie nicht verändert wurde.

Kennwortschutz ermöglicht es Ihnen, beim Erstellen Zugriffsregeln festzulegen. Sie können ein Öffnungskennwort vergeben, um die Anzeige einzuschränken, und ein Besitzerkennwort, 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 gut, wenn vertrauliche PDFs an mehrere Personen verteilt werden sollen, ohne auf ein gemeinsames Kennwort angewiesen zu sein. Weitere Details finden Sie im Artikel zum Verschlüsseln von PDFs mit Kennwörtern und Zertifikaten.

Digitale Signaturen fügen beim Erstellen Authentizität und Integrität hinzu. Docotic.Pdf kann PDFs signieren und dabei Zertifikate aus Dateien, dem Windows-Speicher, Hardware-Token, HSMs oder Cloud-Schlüsseldiensten verwenden. Sie können Zeitstempel und Langzeitvalidierungsdaten einbeziehen, damit Signaturen auch lange nach der Erstellung des Dokuments überprüfbar bleiben. Externe Signatur-Workflows, einschließlich PKCS#11 und Cloud-KMS, werden ebenfalls unterstützt.

Festlegen von PDF-Metadaten

PDF-Metadaten sind beschreibende Informationen, die in einem Dokument eingebettet sind, etwa Titel, Autor, Betreff, Schlüsselwörter, Erstellungsdaten und ähnliche Felder. Sie helfen Software, Suchmaschinen und Dokumentenmanagementsystemen zu verstehen, worum es in einer Datei geht, ohne sie öffnen zu müssen.

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

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

XMP ist das reichhaltigere, strukturierte und standardisierte Format zum Einbetten beschreibender Metadaten. Das Info-Wörterbuch ist einfach und weit verbreitet, aber eingeschränkt, und es ist im PDF-2.0-Standard (ISO 32000-2) zugunsten von XMP-Metadaten veraltet. Docotic.Pdf kann beide Systeme lesen und schreiben und stellt eine Hilfsmethode bereit, um sie synchron zu halten.

Docotic.Pdf aktualisiert einige Metadaten automatisch, bevor es eine PDF-Datei speichert. Beispielsweise setzt die Bibliothek standardmäßig Werte für Producer und Creator. Verwenden Sie Speicheroptionen, um dieses Verhalten zu ändern und explizit gesetzte Metadatenwerte beizubehalten.

XMP-Metadaten

Verwenden Sie die Eigenschaft PdfDocument.Metadata, um auf XMP-Metadaten in einem PDF zuzugreifen und sie zu ändern. Über diese Eigenschaft können Sie mit bekannten Schemas wie XMP Core, Dublin Core und dem PDF-Schema arbeiten sowie eigene benutzerdefinierte 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, was es gut für umfangreiche Metadaten geeignet macht. Der obige Code zeigt außerdem, wie anwendungsspezifische Eigenschaften im benutzerdefinierten XMP-Schema gespeichert werden.

Dokumentinformationswörterbuch

Das Info-Wörterbuch speichert hauptsächlich Textzeichenfolgen. Es ist kompakt und breit unterstützt, aber eingeschränkt. Verwenden Sie das Info-Wörterbuch für die Kompatibilität mit älteren Werkzeugen und bevorzugen Sie in anderen Fällen XMP.

Metadaten synchronisieren

Es ist eine gute Praxis, beide Metadatensysteme synchron zu halten, um Inkonsistenzen zu vermeiden, die Leser und automatisierte Werkzeuge verwirren können.

Verwenden Sie PdfDocument.SyncMetadata, um XMP- und Info-Werte abzugleichen, sodass die entsprechenden Felder übereinstimmen. Die Methode füllt fehlende Info-Eigenschaften aus XMP und füllt analog 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);

Weitere detaillierte Informationen darüber, welche Eigenschaften die Methode synchronisiert, finden Sie im Abschnitt Remarks in der Dokumentation von SyncMetadata.

Konfigurieren von Seitenbeschriftungen und Anzeigeeinstellungen

Ein neu erstelltes PDF kann von expliziter Seitennummerierung, fein abgestimmten Anzeigeeinstellungen und einem Seitenlayout profitieren, das ausgewählt wurde, um den Inhalt des Dokuments effektiver darzustellen. Diese Einstellungen beeinflussen, wie Leser die Datei zuerst sehen und darin navigieren.

Seitenbeschriftungen

Seitenbeschriftungen sind Metadaten, die PDF-Viewer darüber informieren, welche Beschriftung für jede Seite angezeigt werden soll. Verwenden Sie sie, wenn die sichtbare Nummerierung vom physischen Seitenindex abweichen soll. Zum Beispiel, wenn Sie für den Vorspann i, ii, iii und für den Haupttext in Ihrem PDF 1, 2, 3 möchten.

Dieser C#-Code zeigt, wie PDF-Seiten für die ersten drei Seiten mit lateinischen Kleinbuchstaben in römischen Zahlen und für den Rest mit arabischer Nummerierung ab 1 beschriftet werden.

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-Anzeigeeinstellungen

PDF-Anzeigeeinstellungen sind im Dokument eingebettete Empfehlungen, die vorschlagen, wie ein Viewer es darstellen soll. Sie können beispielsweise angeben, dass der Viewer Werkzeugleisten ausblenden, das Fenster zentrieren oder das Fenster an die Seite anpassen soll. Anzeigeeinstellungen ergänzen das Seitenlayout und die Einstellungen für Öffnungsaktionen.

So ändern Sie 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 ignorieren können.

Seitenlayout und Seitenmodus

Das Seitenlayout bestimmt, wie Seiten angeordnet werden, wenn das Dokument geöffnet wird: jeweils eine Seite, fortlaufend in einer Spalte oder als zweiseitige Doppelseiten. Der Seitenmodus steuert, welche UI-Bereiche beim Öffnen sichtbar sind: Lesezeichen/Gliederungen, Anlagen, Miniaturen oder keine.

So geben Sie an, dass das erstellte PDF als zweiseitige Doppelseite mit linker Seite zuerst angezeigt werden soll und der Miniaturenbereich beim Öffnen sichtbar ist:

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 Versionen des PDF-Formats entsprechen, sich in der Byte-Länge unterscheiden und unterschiedlich viel Speicher für die Erzeugung benötigen.

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 Standardwerte. Diese Standardwerte sind sorgfältig gewählt und funktionieren in den meisten Szenarien gut, aber Sie müssen sie möglicherweise dennoch anpassen.

In der Dokumentation der PdfSaveOptions-Klasse finden Sie ausführliche Informationen zu den verfügbaren Optionen und ihren Standardwerten. Die folgenden Abschnitte heben einige der wichtigeren Optionen hervor und geben praktische Empfehlungen.

PDF-Version

Docotic.Pdf verwendet standardmäßig Objekt-Streams, um eine bessere Komprimierung der erzeugten Dateien zu erreichen. Dadurch 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 erzeugten Dokumente anzuzeigen. Das ist normalerweise kein Problem, außer Sie müssen ältere Werkzeuge, ältere Viewer oder eingebettete Geräte unterstützen, die nur ältere PDF-Versionen akzeptieren.

So speichern Sie mit einer älteren PDF-Dateiversion:

using var pdf = new PdfDocument();

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

Um mit der PDF-1.4-Version zu speichern, müssen auch Objekt-Streams deaktiviert werden. Die Bibliothek verwendet keine ältere Version, wenn das Dokument Funktionen enthält, die in späteren Versionen eingeführt wurden.

Reduzierung der Dateigröße

Mehrere Speicheroptionen führen, wenn sie auf true gesetzt sind, dazu, dass Docotic.Pdf kleinere Dateien erzeugt: RemoveUnusedObjects, OptimizeIndirectObjects, WriteWithoutFormatting und UseObjectStreams.

So erzeugen Sie PDFs ohne nicht referenzierte Objekte und zusätzlichen Leerraum, wobei Daten dicht in Objekt-Streams gepackt werden:

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 das PDF vollständig neu geschrieben wird. Bei einem inkrementellen Speichern 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 true ist, hängt die Bibliothek Änderungen an die vorhandene Datei an, statt sie neu zu schreiben. Die vorherigen Cross-Reference- und Objektdaten bleiben unverändert. Die angehängten Daten werden als inkrementelle Aktualisierung bezeichnet, und die aktuelle Aktualisierung zusammen mit allen früheren Aktualisierungen bildet eine neue Revision der Datei.

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

Wann inkrementelle Aktualisierungen erforderlich sind

Wenn Sie einem Dokument, das bereits Signaturen enthält, eine neue digitale Signatur hinzufügen, müssen Sie die Datei inkrementell speichern. Dasselbe gilt, wenn Sie eine zuvor signierte Datei mit neuen Anmerkungen oder Formulardaten aktualisieren. Das vollständige Neuschreiben der Datei würde in diesen Fällen vorhandene Signaturen ungültig machen.

Gleichzeitig ist es am besten, vor dem Anwenden der ersten digitalen Signatur ein nicht inkrementelles (vollständiges) Speichern durchzuführen, damit die signierte Basisdatei eine saubere, vollständig neu geschriebene Datei ist. Das Signieren eines Dokuments, das in früheren Revisionen strukturelle Probleme enthält, kann zu unerwarteten Problemen bei der Signaturvalidierung führen.

Inkrementelles Anhängen ist auch in Workflows erforderlich, die eine prüfbare Revisionshistorie bewahren oder eine ausschließlich anhängende Dokumentspeicherung erzwingen müssen.

Vorteile inkrementeller Aktualisierungen

Inkrementelle Aktualisierungen ermöglichen mehrere Signaturen in derselben Datei und erlauben eine begrenzte Menge an Änderungen nach der Signatur, etwa das Ausfüllen von Formularfeldern, ohne vorhandene Signaturen ungültig zu machen.

Dieser Ansatz bietet zudem schnellere Speicherzeiten bei kleinen Änderungen, da nur die geänderten Daten geschrieben werden. Er bewahrt außerdem die Revisionshistorie des Dokuments, was für Audits und andere Compliance-gesteuerte Workflows wesentlich ist.

Probleme und zu vermeidende Fallstricke

Inkrementelle Aktualisierungen können keine globale Komprimierung anwenden oder veraltete Objekte über die gesamte Datei hinweg entfernen, da sie nur die geänderten Objekte anhängen. Dadurch erzeugen sie in der Regel größere und weniger optimierte Dateien als ein vollständiges Neuschreiben.

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

Sensible oder fehlerhafte Informationen aus früheren Revisionen bleiben wiederherstellbar, und vorhandene PDF-Formatprobleme oder strukturelle Defekte in früheren Revisionen werden durch das Anhängen neuer Daten nicht behoben.

Schließlich haben einige Viewer und Verarbeitungstools Schwierigkeiten mit PDFs mit mehreren Revisionen. Bevor Sie sich auf inkrementelle Aktualisierungen verlassen, stellen Sie sicher, dass alle Verbraucher Ihrer Dokumente Dateien mit mehreren Revisionen verarbeiten können.

PDF-Ausgabe testen

Automatisierte PDF-Tests schützen Releases vor Regressionen in Inhalt und Layout, indem generierte PDFs mit Referenz-PDFs verglichen werden, die in Ihrem Repository oder Artefaktspeicher abgelegt sind. Referenzdateien helfen Ihnen, unbeabsichtigte Änderungen an Text, Schriftarten, Bildern oder Layout zu erkennen, und verringern den Bedarf an manueller QA in jedem Build.

Kombinieren Sie strukturelle Prüfungen, Textextraktion und visuelle Vergleiche für die zuverlässigsten Ergebnisse.

Schneller Vergleich der Ansätze

Vergleich der Dokumentstruktur

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

Diese Methode ist ideal für Test-Workflows mit PDF-Dokumenten, die sicherstellen müssen, dass keine unerwarteten Objekte hinzugefügt oder entfernt wurden. DocumentsAreEqual unterstützt Datei- und Stream-Overloads und kann verschlüsselte PDFs vergleichen.

Ein vollständiges Beispiel, das diese Technik demonstriert, ist in den Docotic.Pdf-Beispielen verfügbar. Zusätzlich zur Demonstration der Verwendung der Methode in regulären .NET-Anwendungen zeigt das Beispiel auch, wie man DocumentsAreEqual in Native AOT Anwendungen verwendet.

PDFs über extrahierten Text verifizieren

Extrahieren Sie Text aus dem gesamten Dokument auf einmal oder aus einzelnen Seiten nacheinander und vergleichen Sie die Zeichenfolgen. Sie können Textextraktionsoptionen verwenden, um den Extraktionsprozess fein abzustimmen, etwa durch Ausschließen des Rechtecks mit der Fußzeile. Um den Vergleich zu erleichtern, können Sie den extrahierten Text in Zeilen oder Wörter aufteilen.

Für strukturierte Prüfungen extrahieren Sie zuerst Text mit Position, Schriftart und anderen detaillierten Informationen zu jedem Fragment, Wort oder Zeichen. Vergleichen Sie dann jedes extrahierte Element mit dem entsprechenden Baseline-Element.

Visuelle Unterschiede erkennen

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

Bevorzugen Sie einen strikten Pixel-für-Pixel-Vergleich, sodass jedes entsprechende Pixel in beiden Bildern übereinstimmen muss. Wenn Ihre Anforderungen kleine Rendering-Abweichungen zulassen, können Sie die Vergleichslogik anpassen, um geringfügige Unterschiede zu tolerieren, aber exakte Pixelgleichheit liefert die zuverlässigsten Ergebnisse.

Erwägen Sie die Verwendung von Hashing als schnellen Vorabcheck, 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, und wenn die Hashes übereinstimmen, sind die Bilder mit sehr hoher Wahrscheinlichkeit gleich. Wenn sich die Hashes unterscheiden, führen Sie den vollständigen Pixel-für-Pixel-Vergleich aus.

Abschluss

Docotic.Pdf bietet ein umfassendes, mehrschichtiges Toolkit zum Erstellen und Manipulieren von PDFs in .NET. Entwickler können zwischen niedrigstufiger Kontrolle mit der Core API, hochstufiger Dokumenterzeugung mit der Layout API oder HTML-zu-PDF-Konvertierung für Workflows wählen, die bereits auf Webtechnologien aufbauen.

Die Bibliothek unterstützt außerdem bildbasierte PDFs, vorlagengetriebene Erzeugung und eine umfangreiche Auswahl interaktiver Funktionen wie Anmerkungen, Links, Lesezeichen, JavaScript-Aktionen und Öffnungsaktionen.

Um Zuverlässigkeit sicherzustellen, enthält Docotic.Pdf Methoden zum Testen der PDF-Ausgabe, damit Änderungen in Ihrer Anwendung keine Regressionen oder unerwarteten Unterschiede einführen.