Создание документов

Конечно, вам необходимо создать PDF-документ с вашими данными. Но достаточно часто вам также нужно зашифровать этот PDF-файл с помощью паролей. И вы обычно хотите добавить метаданные PDF в выходной файл.

Продолжайте читать, чтобы узнать, как дать указание генератору зашифровать PDF-файлы. А ткаже как указать автора документа и ключевые слова.

Эта статья - часть серии статей про Layout API для генерации PDF-файлов. Если вы новичок в работе с API, то сначала прочитайте часть Начало работы с Layout API.

Create & Generate

Точкой входа в Layout API является класс PdfDocumentBuilder. Вы начинаете с создания экземпляра класса с помощью метода Create. Чтобы создать PDF-файл, вы вызываете у созданного экземпляра метод Generate.

Generate может сохранить результат в файл или поток. Любая из версий метода требует делегат типа Action<Document> в качестве второго параметра. В делегате вы описываете документ, который хотите получить. Библиотека сгенерирует PDF-файл на основе описания.

Шифрование

Чтобы зашифровать выходной PDF-файл, вызовите метод Encryption перед вызовов метода Generate.

Вам нужно будет создать и предоставить обработчик шифрования. Чтобы зашифровать PDF с помощью паролей, используйте обработчик типа PdfStandardEncryptionHandler.

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

Вы также можете зашифровать PDF с помощью сертификатов. Ознакомьтесь со статьей Шифрование PDF-документов. Она содержит подробную информацию об обработчиках шифрования и разрешениях PDF.

Метаданные PDF

В некоторых рабочих процессах очень важно указать правильные ключевые слова PDF и автора PDF-файла в выходном PDF. Layout API предоставляет простой способ для этого. Вызовите метод Info перед методом Generate и укажите значения метаданных в делегате.

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(_ => { }));

Опции

Для одного и того же контента библиотека может создавать PDF-файлы с разной внутренней структурой. Вот опции, которые влияют на выходной PDF-файл.

Версия

Используйте метод Version, чтобы установить минимальную версию PDF формата для выходного PDF-файла.

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

Обратите внимание, что библиотека может создать PDF-файл большей версии, чем указано. Это происходит, когда содержимое документа требует более новой версии. Другими словами: когда в документе используются функции, недоступные в указанной версии стандарта PDF.

Потоки объектов

По умолчанию библиотека использует потоки объектов в создаваемых PDF-файлах. Это помогает создавать файлы меньшего размера и с лучшим сжатием.

Используя метод ObjectStreams, вы можете поручить API создавать файлы PDF без потоков объектов.

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

Я советую вам продолжать использовать потоки объектов, если нет каких-либо нормативных требований. Если другие части вашего рабочего процесса не могут обрабатывать документы с потоками объектов, то вы знаете как отключить использование таких потоков.

Поставщик потоков

Библиотека использует потоки в качестве промежуточного хранилища. При создании PDF-файла это делается для изображений и других крупных объектов. Библиотека получает потоки через поставщика потоков. Любой экземпляр PdfDocumentBuilder всегда использует какого-то поставщика.

По умолчанию библиотека использует PdfMixedStorageStreamProvider. Эта реализация поставщика потоков предоставляет потоки, которые хранят данные в памяти. Эти потоки сбрасывают свое содержимое во временные файлы, когда данных слишком много. Это позволяет снизить потребление памяти и избежать фрагментации LOH.

Вы можете использовать собственную реализацию интерфейса IPdfStreamProvider при создании PDF-файлов. Одной из причин изменения могут быть медленные и/или дорогостоящие дисковые операции. Облачные среды могут соответствовать этому описанию.

Этот код показывает, как полностью создать PDF-файл в памяти, без временных файлов. Обратите внимание, что для этого потребуется гораздо больше памяти, чем при использовании параметров по умолчанию.

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

Библиотека в конечном итоге вызывает Dispose для каждого потока, который она получила от поставщика потоков. Вы должны самостоятельно избавиться от экземпляра поставщика потоков.