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

Перевод Bit Miracle. Автор оригинала: Sergey Bobrovsky

Обновлено 2 июля 2026

Конечно, вам нужно сгенерировать 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. Это помогает создавать файлы меньшего размера и лучше сжатые.

Вы можете указать API создавать PDF-файлы без потоков объектов с помощью метода ObjectStreams.

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

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

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

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

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

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

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

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

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