Gebäudedokumente

Natürlich müssen Sie mit Ihren Daten ein PDF-Dokument generieren. Aber oft genug möchte man die PDF-Datei auch mit Passwörtern verschlüsseln. Und normalerweise möchten Sie der Ausgabedatei PDF-Metadaten hinzufügen.

Lesen Sie weiter, um zu erfahren, wie Sie den Generator anweisen, PDF-Dateien zu verschlüsseln. So geben Sie den Autor und die Schlüsselwörter des Dokuments an.

Dieser Artikel ist Teil einer Serie über die Layout-API für die PDF-Generierung. Wenn Sie mit der API noch nicht vertraut sind, lesen Sie zuerst den Teil Erste Schritte mit der Layout-API.

Create & Generate

Der Einstiegspunkt der Layout-API ist die Klasse PdfDocumentBuilder. Sie beginnen mit der Erstellung einer Instanz der Klasse mit der Methode Create. Um ein PDF zu generieren, rufen Sie die Methode Generate der Klasse auf.

Generate kann die Ausgabe in einer Datei oder einem Stream speichern. Jede Version der Methode erfordert einen Delegaten vom Typ Action<Document> als zweiten Parameter. Im Delegaten beschreiben Sie das Dokument, das Sie erhalten möchten. Die Bibliothek generiert auf Grundlage der Beschreibung ein PDF.

Verschlüsselung

Um das Ausgabe-PDF zu verschlüsseln, rufen Sie die Methode Encryption vor der Methode Generate auf.

Sie müssten einen Verschlüsselungshandler erstellen und bereitstellen. Um PDFs mit Passwörtern zu verschlüsseln, verwenden Sie einen Handler vom Typ PdfStandardEncryptionHandler.

PdfDocumentBuilder.Create()
    .Encryption(new PdfStandardEncryptionHandler("owner", "user"))
    .Generate("encrypted-with-password.pdf", doc => doc.Pages(_ => { }));

Sie können PDF auch mit Zertifikaten verschlüsseln. Lesen Sie den Artikel PDF-Dokumente verschlüsseln. Es enthält detaillierte Informationen zu Verschlüsselungshandlern und PDF-Berechtigungen.

Metadaten der PDF-Datei

In einigen Arbeitsabläufen ist es sehr wichtig, in der Ausgabe-PDF die richtigen PDF-Schlüsselwörter und den richtigen PDF-Autor anzugeben. Die Layout-API bietet hierfür eine einfache Möglichkeit. Rufen Sie die Methode Info vor der Methode Generate auf und geben Sie die Metadatenwerte im Delegaten an.

PdfDocumentBuilder.Create()
    .Info(info =>
    {
        info.Author = $"{Environment.UserName}";
        info.Title = "Generate encrypted PDF with custom metadata";
        info.Keywords = "Metadata keywords encryption";
    })
    .Generate("metadata.pdf", doc => doc.Pages(_ => { }));

Optionen

Für denselben Inhalt kann die Bibliothek PDF-Dateien mit unterschiedlicher interner Struktur erstellen. Diese Optionen wirken sich auf die Ausgabe-PDF aus.

Version

Verwenden Sie die Methode Version, um die minimale PDF-Formatversion für die Ausgabe-PDF festzulegen.

PdfDocumentBuilder.Create()
    .Version(PdfVersion.Pdf17)
    .Generate("version.pdf", doc => doc.Pages(_ => { }));

Bitte beachten Sie, dass die Bibliothek ein PDF mit einer größeren Version als angegeben erstellen kann. Dies geschieht, wenn der Inhalt des Dokuments eine neuere Version erfordert. Anders ausgedrückt: wenn das Dokument Funktionen verwendet, die in der angegebenen Version des PDF-Standards nicht verfügbar sind.

Objektströme

Standardmäßig verwendet die Bibliothek Objektströme in generierten PDFs. Dies trägt dazu bei, kleinere, besser komprimierte Dateien zu erstellen.

Mit der Methode ObjectStreams können Sie die API anweisen, PDF-Dateien ohne Objektströme zu erstellen.

PdfDocumentBuilder.Create()
    .ObjectStreams(false)
    .Generate("no-object-streams.pdf", doc => doc.Pages(_ => { }));

Ich empfehle Ihnen, weiterhin Objektströme zu verwenden, sofern keine gesetzlichen Anforderungen bestehen. Oder wenn andere Teile Ihres Workflows Dokumente nicht mit Objektströmen verarbeiten können.

Stream-Anbieter

Die Bibliothek verwendet Streams als Zwischenspeicher. Beim Generieren einer PDF-Datei gilt dies für Bilder und andere große Objekte. Die Bibliothek erhält Streams über den Stream-Anbieter. Der aktuellen PdfDocumentBuilder-Instanz ist immer eine zugeordnet.

Die Bibliothek verwendet standardmäßig PdfMixedStorageStreamProvider. Diese Stream-Provider-Implementierung stellt Streams bereit, die Daten im Speicher halten. Diese Streams leeren ihren Inhalt in temporäre Dateien, wenn zu viele Daten vorhanden sind. Dadurch kann der Speicherverbrauch reduziert und eine LOH-Fragmentierung vermieden werden.

Sie können beim Generieren von PDF-Dateien Ihre eigene Implementierung der Schnittstelle IPdfStreamProvider verwenden. Ein Grund für die Änderung könnten langsame und/oder teure Festplattenvorgänge sein. Cloud-Umgebungen könnten in diese Beschreibung passen.

Dieser Code zeigt, wie man PDF-Dateien vollständig im Speicher generiert, ohne temporäre Dateien. Bitte beachten Sie, dass hierfür wesentlich mehr Speicher benötigt wird als bei den Standardoptionen.

using (var memoryOnlyProvider = new PdfMemoryStreamProvider())
{
    PdfDocumentBuilder.Create()
        .StreamProvider(memoryOnlyProvider)
        .Generate("created-without-temp-files.pdf", doc => doc.Pages(_ => { }));
}

Die Bibliothek ruft schließlich Dispose für jeden Stream auf, den sie über den Stream-Anbieter erhält. Sie müssen die Stream-Provider-Instanz selbst entsorgen.