DevExpress PDF Document API позволяет из кода создавать и изменять PDF, добавлять текст, изображения и графику, переставлять страницы, заполнять формы, искать и скрывать данные, настраивать шифрование, метаданные, печать и экспорт страниц в изображения. Работа строится через объектную модель PdfDocument, коллекции Pages, Fields и Annotations, поэтому операции удобно объединять в воспроизводимый конвейер обработки документов.

Основной рабочий объект открывает файл или поток, предоставляет доступ к страницам и их содержимому, а затем сохраняет результат в новый поток. Вместо команд визуального редактора используются классы Page, TextFragment, ImageFragment, FormField и конкретные типы аннотаций; это позволяет точно повторять одну и ту же обработку для сотен документов без ручных действий.

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

Как устроен рабочий процесс с PDF

В центре API находится класс PdfDocument. Новый документ создаётся пустым конструктором, существующий — конструктором, которому передают читаемый поток и при необходимости объект LoadOptions. После загрузки становятся доступны коллекции Pages, Fields, Attachments, дерево структуры, метаданные и разрешения безопасности. Изменения вносятся непосредственно в эти объекты, а метод Save сериализует получившуюся модель в выходной поток.

Такой подход требует заранее определить владение потоками. Если исходный поток должен оставаться доступным после завершения загрузки, проверяют настройку DetachStreamAfterLoadComplete; если документ обрабатывается внутри короткого задания, обычно проще держать поток и PdfDocument в блоках using. Выходной файл следует открывать с режимом FileMode.Create, иначе старый хвост более длинного файла может сохраниться после перезаписи.

Коллекции имеют нулевую индексацию, а диапазоны поиска и экспорта страниц задаются индексами, а не печатными номерами. В производственном коде полезно отделять пользовательские номера страниц от индексов: строку страницы 1–3 преобразуют в значения 0–2 только после проверки границ. Это устраняет типичную ошибку, при которой обработка начинается со второй страницы или заканчивается исключением выхода за пределы коллекции.

Добавление пакета и подготовка проекта

Для проекта .NET пакет ищут в диспетчере NuGet по точному идентификатору DevExpress.Docs.Pdf. После установки в код добавляют пространство имён DevExpress.Docs.Pdf; для размеров бумаги, графических типов и изображений могут потребоваться пространства имён DevExpress Drawing. В проекте .NET Framework вместо PackageReference допустимо подключить установленные сборки, однако все зависимые DLL должны быть одной совместимой поставки.

Если Visual Studio не видит пакет, сначала проверяют выбранный канал NuGet и снимают фильтр предварительных пакетов только тогда, когда это действительно требуется. Ошибки восстановления зависимостей часто связаны не с PDF-кодом, а с недоступным фидом, устаревшим кэшем или конфликтом версий DevExpress.Data, DevExpress.Drawing и DevExpress.Docs.Core. Практический порядок исправления: очистить локальный кэш NuGet, удалить несогласованные явные ссылки, восстановить пакет заново и выполнить полную пересборку решения.

Для автоматической сборки достаточно хранить PackageReference в файле проекта и не добавлять DLL в репозиторий. Лицензионный ключ регистрируют в среде сборки по правилам DevExpress; без корректной регистрации оценочный режим может выдавать предупреждения. Документация разрешает оценку в течение ограниченного периода, но эксплуатация в производственном коде требует коммерческой лицензии.

Создание документа с нуля

Минимальный документ формируют в четыре шага: создают PdfDocument, добавляют страницу, помещают на неё фрагменты и сохраняют поток. Страницу можно добавить по стандартному формату бумаги через DXPaperKind либо создать с собственными размерами. Пустой объект без страниц не является полезным конечным PDF, поэтому перед сохранением проверяют, что коллекция Pages содержит хотя бы один элемент.

using DevExpress.Docs.Pdf;
using DevExpress.Drawing.Printing;
using System.Drawing;

using PdfDocument document = new PdfDocument();
Page page = document.Pages.Add(DXPaperKind.A4);
page.AddFragment(new TextFragment {
    Text = "Акт приёма-передачи",
    Location = new PointF(48, 790),
    Font = new TextFont("Arial", TextFontStyle.Bold),
    FontSize = 18
});
using FileStream output = File.Create("result.pdf");
document.Save(output);

Координаты относятся к странице, начало системы находится в левом нижнем углу, единицей служит пункт, а один дюйм равен 72 пунктам. Это отличается от экранной графики, где ось Y часто направлена вниз. При переносе макета из CSS или изображения нужно преобразовывать координату: желаемое расстояние от верхнего края вычитают из высоты страницы с учётом высоты самого объекта.

Размеры A4, Letter и других стандартов лучше задавать перечислением, чтобы не переносить магические числа между проектами. Собственные форматы оправданы для этикеток, чеков и билетов. Перед генерацией серии документов проверяют, что ширина и высота не перепутаны, а ориентация реализована ожидаемым способом: поворот содержимого и изменение геометрии страницы дают разные результаты в печати и просмотрщиках.

Текстовые фрагменты и абзацы

Однострочный текст

Для короткой надписи подходит TextFragment. У него задают текст, положение, шрифт, кегль, начертание и заливку. Объект можно добавить через Page.Fragments.Add или через специализированный метод страницы. Если требуется изменить уже загруженный документ, коллекцию фрагментов обходят, находят нужный TextFragment и меняют его свойства без ручного редактирования потока PDF-команд.

Шрифт задаётся по имени семейства. На сервере это имя должно разрешаться в доступный шрифт; наличие гарнитуры на компьютере разработчика не гарантирует её наличие в контейнере Linux. Для предсказуемой верстки устанавливают шрифты в окружение развертывания, проверяют кириллицу, цифры и специальные символы, а после генерации открывают документ независимым просмотрщиком и убеждаются, что замена гарнитуры не изменила ширину строк.

Многострочный текст

Для абзаца используют ParagraphFragment. Помимо текста и шрифта, ему задают ширину, высоту и параметры выравнивания. Ограничивающий прямоугольник важен: без него длинный текст не знает, где переносить строки. Если содержимое может не поместиться, заранее измеряют доступную область, уменьшают кегль по контролируемому правилу или разбивают данные на несколько страниц; молчаливое обрезание текста в юридическом документе недопустимо.

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

Изображения и графические элементы

ImageFragment принимает изображение DevExpress Drawing и позволяет задать положение, размеры и преобразования. Поддерживаются BMP, JPEG, PNG, EMF, EMF+, TIFF, GIF и SVG. Для фотографии рационален JPEG, для схемы с прозрачностью — PNG, для масштабируемого логотипа — SVG; выбор формата до вставки влияет на размер конечного PDF и качество при увеличении.

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

Векторные фигуры создают через GraphicsPath и PathFragment. Контур может содержать отрезки и кривые Безье, а фрагмент — параметры обводки, сплошную или градиентную заливку и действие рисования. Так формируют рамки, разделители, штампы, простые диаграммы и фоны без растрирования. Для повторяемых элементов предусмотрены шаблоны форм: один ресурс добавляют на несколько страниц, уменьшая дублирование и упрощая синхронное изменение макета.

Скос, поворот и масштабирование изображения нужно применять осознанно. Преобразование меняет визуальную геометрию, но не обязательно изменяет исходное разрешение. Если фотографию на 20 мегапикселей показывают в прямоугольнике 200×100 пунктов, документ всё равно может хранить крупный ресурс. Перед вставкой изображение уменьшают до достаточного разрешения и выбирают компрессию, иначе пакет счетов быстро разрастётся до сотен мегабайт.

Операции со страницами

Коллекция Pages поддерживает добавление страницы в конец и вставку по индексу. Существующие страницы можно копировать, переносить внутри документа и клонировать в другой документ. При сборке досье из отдельных файлов порядок следует задавать явным списком, а не полагаться на сортировку имён: 10.pdf в лексикографическом порядке окажется перед 2.pdf.

Поворот страницы и поворот её содержимого — разные операции. Изменение угла страницы сообщает просмотрщику, как показывать и печатать лист; преобразование содержимого физически меняет положение фрагментов. Для скана, сохранённого боком, чаще достаточно угла страницы. Для подготовки макета, где элементы должны реально занять новые координаты, используют поворот содержимого и проверяют обрезку по CropBox.

Метод ScaleContent масштабирует содержимое по горизонтали и вертикали, а OffsetContent сдвигает его. Комбинация полезна для добавления полей под штамп, нумерацию или служебный колонтитул: существующее содержимое слегка уменьшают и смещают, затем свободную область заполняют новым фрагментом. Масштабирование 0,5 уменьшает объект до половины исходного размера; значения по осям можно задавать раздельно, но неравномерное масштабирование искажает текст и изображения.

Изменение размера самой страницы не гарантирует автоматического масштабирования содержимого. Если A4 заменить на Letter только геометрией листа, часть объектов может оказаться за границей. Безопасный алгоритм вычисляет коэффициент вписывания, масштабирует содержимое, центрирует его смещением и только затем задаёт новую ширину и высоту. После удаления страниц проверяют закладки, ссылки, поля формы и аннотации, которые могли ссылаться на удалённые объекты.

Объединение и разделение файлов

Для объединения документов исходные файлы открывают по очереди и добавляют страницы в целевой PdfDocument. Метод добавления документа удобен, когда нужен весь файл, а копирование выбранных страниц — когда приложение собирает приложение к договору из заданных диапазонов. Перед операцией проверяют пароли, доступность потоков и допустимость извлечения данных из защищённого PDF.

Разделение строится обратным образом: для каждого требуемого диапазона создают новый документ, копируют туда страницы в нужном порядке и сохраняют отдельным потоком. Имена файлов формируют из безопасного идентификатора и фактического диапазона, например case-184_pages-001-010.pdf. Нельзя использовать заголовок документа без очистки, поскольку символы из метаданных могут быть недопустимы в имени файла.

При объединении метаданные не сливаются автоматически по бизнес-правилам. Итоговому файлу назначают собственные Title, Author, Subject и Keywords, а не случайно оставляют сведения первого входного PDF. Аналогично проверяют вложения и поля: одинаковые имена полей из нескольких форм могут конфликтовать, поэтому для пакетной сборки желательно предварительно переименовать поля или превратить заполненные формы в статическое содержимое по выбранной политике.

Поиск, форматирование и удаление текста

Метод FindText выполняет поиск по документу или заданному диапазону страниц. TextSearchOptions задаёт чувствительность к регистру и поиск целых слов. Результаты группируются по страницам в TextSearchInfo; список Matches содержит геометрию совпадений, а Groups даёт доступ к фрагментам, которые можно форматировать или удалять.

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

Замена строки в PDF сложнее замены в текстовом файле. Новое слово может быть длиннее, выйти за границу строки или перекрыть соседний объект. Безопасно заменять значения фиксированной длины, номера и метки в заранее подготовленном шаблоне. Для произвольного абзаца лучше удалить исходные фрагменты, рассчитать новый блок и проверить переносы; библиотека предоставляет объекты для редактирования, но бизнес-правило компоновки остаётся задачей приложения.

Если поиск ничего не вернул, сначала выясняют, есть ли в PDF текстовый слой. Скан страницы может состоять только из изображения; тогда FindText не выполняет OCR. Другие причины — раздельное кодирование символов, нестандартный шрифт, лигатуры или пробелы, представленные позиционированием. Для диагностики экспортируют страницу в изображение, проверяют возможность выделения текста в независимом просмотрщике и сравнивают поиск по короткому фрагменту без учёта регистра.

Надёжное скрытие конфиденциальных данных

Чёрный прямоугольник поверх текста только маскирует его визуально: исходные символы могут остаться в содержимом, копироваться в буфер обмена и извлекаться программой. Для удаления персональных данных используют RedactionAnnotation и применение редакции к документу. Геометрию областей удобно получать из Matches результатов поиска, после чего можно задать цвет заливки и при необходимости текст замены.

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

Следует учитывать не только текст страницы. Конфиденциальные данные могут находиться в метаданных, вложениях, комментариях, значениях скрытых полей формы, JavaScript и альтернативном тексте структуры. Полная санитарная обработка должна обходить эти коллекции отдельно. Если документ пришёл из внешней системы, после удаления содержимого разумно сформировать новый файл с минимально необходимыми метаданными и без неизвестных вложений.

Комментарии и аннотации

Коллекция Page.Annotations хранит визуальные и интерактивные объекты страницы. Поддерживаются заметки, свободный текст, выделение, подчёркивание, зачёркивание, волнистая линия, линии и многоугольники, круги и прямоугольники, рукописные штрихи, штампы, вложения, звуковые аннотации, ссылки, водяные знаки и редакция. Каждый тип имеет собственную геометрию и параметры внешнего вида.

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

Комментарии и рецензии формируют историю обсуждения. API позволяет добавлять ответы и статусы проверки, поэтому приложение может переносить результат согласования из бизнес-системы прямо в PDF. При обновлении комментариев нельзя идентифицировать их только по видимому тексту: одинаковая фраза может встречаться несколько раз. Надёжнее хранить связь с объектом аннотации и страницей либо записывать собственный идентификатор в доступное поле модели.

Удаление всех аннотаций перед публикацией иногда оправдано, но оно также удалит полезные ссылки, подписи полей и редакционные отметки. Политику очистки задают по типам: например, убрать заметки и звуковые объекты, сохранить ссылки, применить редакцию, а затем удалить только использованные redaction-аннотации. Итог проверяют в нескольких просмотрщиках, поскольку внешний вид аннотации может зависеть от сохранённого appearance-потока.

Интерактивные формы AcroForm

Поле и виджет

Модель формы разделяет данные и визуальное представление. FormField хранит имя, значение и параметры, а виджет-аннотация показывает поле на конкретной странице. Поле добавляют в PdfDocument.Fields, затем создают подходящий виджет и помещают его в Page.Annotations. Одно поле может иметь несколько виджетов, что полезно для повторяющегося значения на разных страницах.

Координаты формы используют ту же систему с началом в левом нижнем углу и пунктами. Для текстового поля создают TextBoxField и TextBoxWidgetAnnotation, для флажка — CheckBoxField, для группы переключателей — RadioGroupField с отдельными элементами, для выбора — ListBoxField или ComboBoxField. SignatureField задаёт область подписи и предоставляет сведения о подписанте, времени, причине и контакте.

Заполнение и чтение значений

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

Данные формы импортируются и экспортируются в FDF, XFDF, XML и TXT. Это позволяет хранить шаблон отдельно от значений: приложение получает пустую форму, импортирует данные конкретного клиента и сохраняет персонализированный PDF. При обмене XML проверяют кодировку и имена полей; неизвестное имя не должно тихо игнорироваться, если оно соответствует обязательному бизнес-реквизиту.

Форматирование и JavaScript

FormFieldValueFormat задаёт форматы даты, времени, числа, процента и специальных строк. Для более сложных правил предусмотрены сценарии форматирования, ввода, проверки и пересчёта. Такие сценарии выполняются только просмотрщиками, поддерживающими JavaScript. Поэтому критическую валидацию нельзя оставлять внутри PDF: сервер должен повторно проверить полученные значения до сохранения в базе или выпуска документа.

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

Шифрование и разрешения

Защищённый документ открывают через LoadOptions с паролем. После загрузки свойства AccessMode, PrintPermissions, ModificationPermissions, InteractivityPermissions и DataExtractionPermissions показывают, какой доступ получен. Код должен проверять эти значения до изменения файла, а не рассчитывать, что успешное открытие автоматически разрешает любые операции.

Для сохранения с защитой создают EncryptionOptions, задают пароль пользователя и владельца, алгоритм и разрешения. Пароль пользователя ограничивает открытие, пароль владельца даёт полный доступ к настройкам. Поддерживается AES-256, а разрешения позволяют запретить или ограничить печать, изменение, интерактивные действия и извлечение данных. Пароли не следует хранить в исходном коде или журналах; их получают из защищённого хранилища секретов и очищают из диагностических сообщений.

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

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

Метаданные PDF и XMP

Свойство Metadata объединяет базовые сведения PDF и XMP-пакет. В DocumentInfo задаются заголовок, автор, тема, ключевые слова и производитель. Эти значения используются просмотрщиками, системами индексации и корпоративными хранилищами, поэтому их заполняют из доверенных бизнес-данных, а не копируют из случайного входного файла.

XMP хранит структурированные XML-метаданные. API умеет загрузить пакет из строки, массива байтов или потока, работать со стандартными схемами PDF, PDF/A, PDF/UA, Dublin Core и управления правами, а также регистрировать пользовательские пространства имён. Неизвестную схему следует сохранять только тогда, когда приложение понимает её назначение; в противном случае в документе могут остаться скрытые идентификаторы или персональные сведения.

Базовые поля и XMP могут противоречить друг другу. Режим синхронизации выбирают при загрузке, сохранении или вызывают вручную. Вариант Info-to-XMP делает базовую информацию приоритетной копией, XMP-to-Info — наоборот, автоматический режим разрешает конфликт по установленному правилу. Для пакетной обработки правило фиксируют в конфигурации, иначе одинаковые документы могут получить разные заголовки в разных системах.

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

Доступные PDF и дерево структуры

Тегированный PDF содержит логическое дерево, которое связывает визуальные фрагменты с заголовками, абзацами, списками, таблицами и другими смысловыми элементами. Экранный диктор опирается на эту структуру, а не на координаты объектов. Свойство StructureTree предоставляет корень, а дочерние StructureElement создаются с типами из наборов PDF 1.7 или PDF 2.0.

Для нового документа сначала добавляют корневой элемент Document, затем разделы, заголовки, абзацы и таблицы. Фрагмент добавляют через соответствующий структурный элемент, чтобы визуальное содержимое сразу получило семантическую связь. Для таблицы создают Table, THead, TBody, строки TR и ячейки TH или TD; у заголовочных ячеек задают область действия по строке или столбцу.

Порядок в дереве должен соответствовать порядку чтения, даже если визуально элементы расположены в две колонки. Автоматическое следование координатам недостаточно: боковая панель, номер страницы и основной текст могут оказаться в неправильной последовательности. Для изображений задают альтернативное описание, а декоративные объекты исключают из смыслового потока.

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

Вложения и электронные счета ZUGFeRD

Коллекция Attachments позволяет добавлять и удалять файлы, связанные с PDF. Вложение имеет имя, описание, данные и отношение к документу. Перед добавлением проверяют размер, MIME-тип и допустимое расширение; PDF с вложенным исполняемым файлом может быть заблокирован почтовой системой или политикой безопасности.

Для электронного счёта ZUGFeRD визуальная часть объединяется с XML-данными в PDF/A-3. Метод AttachZugferdInvoice принимает XML из файла или потока, вариант стандарта и уровень соответствия. Поддерживаются семейства ZUGFeRD 1.0, 2.0.1+, 2.1+ и 2.3.2+, включая уровни Minimal, Basic и другие предусмотренные профили.

XML должен быть сформирован и проверен до встраивания. Библиотека может создать требуемую упаковку PDF/A-3 и метаданные, но не исправляет бизнес-ошибки в реквизитах счета. После сохранения полезно извлечь вложение обратно, сравнить хеш с исходным XML и прогнать итоговый файл через валидатор выбранного профиля.

Если документ содержит обычные вложения и ZUGFeRD XML, политика обработки должна отличать их по отношению и назначению. При санитарной очистке нельзя удалить обязательный XML счета вместе с произвольными приложениями. И наоборот, наличие корректного XML не делает безопасными остальные вложенные файлы.

Печать на Windows, Linux и macOS

Метод Print принимает PrintOptions. В параметрах задают ориентацию, диапазон, масштабирование, двусторонний режим и печать заметок. На Windows используется системная инфраструктура печати, а в Unix-подобных средах работа строится через CUPS. Приложение должно проверять наличие очереди и доступность принтера до начала длинного задания.

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

Свойство печати заметок определяет, попадут ли sticky notes в результат. Если документ содержит редакционные комментарии, их случайная печать может раскрыть внутреннее обсуждение. Перед выпуском печатной партии приложение подсчитывает аннотации, применяет утверждённую политику и записывает её в журнал задания.

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

Экспорт страниц в изображения

ExportToImages принимает индексы страниц и возвращает изображения. Можно экспортировать одну страницу или выборку, а результат сохранить как Bitmap либо SVG. Растровый формат подходит для предпросмотра, распознавания и публикации миниатюр; SVG сохраняет векторную природу многих элементов и лучше масштабируется в интерфейсе.

Параметры ImageExportOptions управляют типом, качеством и размером результата. Для миниатюры не следует рендерить страницу в полиграфическом разрешении и затем уменьшать её: это расходует память и процессор. Для OCR, напротив, слишком маленькое изображение ухудшит распознавание. Профиль экспорта выбирают по задаче и фиксируют в конфигурации.

Возвращённые изображения нужно освобождать после сохранения. При экспорте большого документа обработку выполняют порциями, чтобы не держать весь набор страниц в памяти. Индексы проверяют заранее; если пользователь запросил страницы 1, 3 и 5, в код передают 0, 2 и 4 после проверки фактического количества листов.

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

Шрифты, цвета и точность отображения

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

Цвета доступны в разных пространствах, включая DeviceRGB, DeviceCMYK, градации серого, ICCBased, Lab, Separation и DeviceN. Для экранного документа обычно достаточно RGB, для типографии могут потребоваться CMYK и профиль. Преобразование цвета без согласованного профиля способно заметно изменить фирменные оттенки, поэтому PDF для печати проверяют в процессе допечатной подготовки.

Сплошные заливки создаются через SolidFill, градиенты — через осевые, радиальные и сеточные варианты. Обводка управляется Outline, стилем линии, толщиной, соединениями и штриховым шаблоном. Сложные сеточные заливки оправданы для существующего содержимого или специальных макетов; для обычных форм и счетов простые ресурсы быстрее рендерятся и меньше увеличивают файл.

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

Ссылки, действия и параметры просмотра

Ссылочная аннотация может вести к месту в текущем документе, другой PDF или URI. Для внутреннего перехода создают destination с целевой страницей и режимом отображения: вписать страницу, ширину, высоту или прямоугольник. После удаления и перестановки страниц все переходы проверяют, поскольку ссылка на прежний индекс может указывать не туда.

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

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

Производительность и работа с большими файлами

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

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

Один экземпляр PdfDocument не следует изменять одновременно из нескольких потоков без прямой гарантии потокобезопасности. Параллелизм достигают обработкой разных документов в отдельных экземплярах. Степень параллелизма ограничивают по памяти и процессору; десять одновременных экспортов многостраничных сканов способны создать больше нагрузки, чем сотня простых операций с метаданными.

Кэш изображений ускоряет повторное использование ресурсов, но увеличивает память. Для шаблонов с одним логотипом кэш полезен, для потока уникальных фотографий — может быть вреден. Профилирование должно включать сборку мусора, количество открытых дескрипторов, время загрузки, преобразования и сохранения отдельно.

Безопасная обработка недоверенных PDF

Входной PDF рассматривают как недоверенные данные. До загрузки ограничивают размер файла, глубину очереди и время обработки. Расширение .pdf не доказывает формат; проверяют заголовок и обрабатывают исключения парсинга. Повреждённый файл не должен останавливать весь пакет.

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

Пароли, персональные данные и содержимое документов не записывают в обычный журнал. Для диагностики достаточно идентификатора задания, типа операции, числа страниц, размеров, времени и кода исключения. Фрагмент текста допускается логировать только после маскирования и по утверждённой политике.

После обработки выходной файл открывают повторно новым экземпляром PdfDocument. Эта проверка ловит ошибки незавершённого потока, повреждения и некоторые несогласованные объекты. Для документов с требованиями PDF/A, PDF/UA или ZUGFeRD дополнительно нужен профильный валидатор, поскольку успешное открытие не подтверждает соответствие стандарту.

Диагностика типичных ошибок

Пакет установлен, но типы не находятся

Проверяют точное пространство имён, целевую платформу и восстановление зависимостей. Если код использует DevExpress.Docs.Pdf, ссылка на другой пакет обработки документов не предоставляет ту же объектную модель. После изменения PackageReference удаляют каталоги bin и obj, восстанавливают пакеты и убеждаются, что в выводе сборки нет конфликтующих сборок DevExpress.

Документ не открывается из потока

Поток должен быть читаемым и находиться в начале, если он уже использовался. Для MemoryStream устанавливают Position = 0. Защищённому файлу передают пароль через LoadOptions. Если ошибка остаётся, сохраняют поток во временный файл, проверяют сигнатуру и открывают независимым просмотрщиком; это отделяет повреждение входа от ошибки интеграции.

Текст появился не там

Чаще всего перепутано направление оси Y или использованы пиксели вместо пунктов. Пересчитывают координаты относительно левого нижнего угла и учитывают высоту текста. Для повернутой страницы проверяют, относится ли преобразование к странице или содержимому. Отладочная рамка вокруг ожидаемой области быстро показывает ошибку геометрии.

После замены текст перекрывает соседние элементы

PDF не выполняет автоматическую перевёрстку всей страницы. Измеряют новый текст, задают ограничивающий прямоугольник, уменьшают кегль в разрешённых пределах либо перестраивают блок. Если исходный документ не был шаблоном для редактирования, безопаснее закрыть старую область редакцией и добавить новый фрагмент в заранее проверенное место.

Форма отображается по-разному

Некоторые просмотрщики используют сохранённый appearance, другие генерируют его из значения и шрифта. Явно задают внешний вид виджета, доступный шрифт и размер, затем тестируют Adobe Acrobat, браузерный просмотрщик и целевое приложение. JavaScript-форматирование не считают обязательным, потому что оно может быть отключено.

Печать на Linux не запускается

Проверяют установку и доступность CUPS, права пользователя сервиса, имя очереди и драйвер. Сначала отправляют тестовую страницу системной командой, затем проверяют параметры PrintOptions. В контейнере печать часто требует отдельной настройки сокета CUPS и не появляется автоматически после добавления NuGet-пакета.

Практический конвейер пакетной обработки

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

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

Контроль повторно открывает выход, проверяет количество страниц, отсутствие искомых секретов, наличие обязательного текста, разрешения, метаданные и хеш вложенного XML. Для визуального контроля экспортируют выборочные страницы. Публикация происходит только после всех проверок; временные файлы удаляются по политике хранения.

Повторная обработка одного задания должна быть идемпотентной. Штамп не должен добавляться второй раз, страницы — повторно дублироваться, а имя результата — бесконечно расширяться. Для этого приложение записывает собственную метку в метаданные или внешнюю базу и проверяет её перед запуском операции.

Тестирование кода, который меняет PDF

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

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

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

Для кроссплатформенного развертывания одинаковые тесты запускают на Windows и Linux. Особое внимание уделяют шрифтам, печати и путям файлов. Совпадение результатов на компьютере разработчика не гарантирует работу контейнера с другим набором гарнитур и локалью.

Ограничения, которые нужно учитывать

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

Объектная модель требует знания PDF-геометрии, потоков и типов содержимого. Координаты, поля, аннотации и структура документа связаны, поэтому простая операция может потребовать нескольких объектов. Для команды без опыта PDF полезно сначала реализовать узкий сценарий и покрыть его тестами, а не строить универсальный редактор поверх API.

Документация помечает рассматриваемую объектную модель как Community Technology Preview и прямо не рекомендует использовать её в критичных производственных системах. Это означает, что перед внедрением нужно оценить риск изменения API, провести нагрузочные тесты и предусмотреть возможность обновления кода. Для процесса, где ошибка блокирует юридически значимый документооборот, предварительный статус является существенным ограничением.

OCR не является частью описанного поиска текста. Если страница состоит из скана, сначала нужен отдельный движок распознавания и создание текстового слоя либо получение координат распознанных слов. Также API не заменяет профильные валидаторы PDF/A и PDF/UA: оно предоставляет необходимые модели и операции, но окончательное соответствие проверяется специализированным инструментом.

Производственное использование требует лицензии. При выборе архитектуры учитывают не только код разработки, но и лицензирование сборочных агентов, серверов и распространения по условиям DevExpress. Конкретные права проверяют по договору организации, а не по предположению, что пакет из публичного NuGet автоматически разрешён для любого коммерческого проекта.

Загрузка и сохранение через потоки

Потоковая модель позволяет не привязывать обработку к файлам на диске. Вход может прийти из объекта загрузки ASP.NET, базы данных, облачного хранилища или очереди, а выход — сразу записываться в ответ, временный объект или защищённый контейнер. При этом поток обязан поддерживать операции, которые ожидает конкретный конструктор или метод сохранения; доступ только на запись не подходит для загрузки, а закрытый поток вызовет исключение до разбора PDF.

Для входного FileStream обычно используют FileAccess.Read и совместное чтение только по необходимости. Если приложение планирует сохранять поверх того же файла, безопаснее всё равно писать во временный путь: успешная загрузка не гарантирует успешное завершение всех изменений. После сохранения временный документ повторно открывают, проверяют и лишь затем атомарно заменяют исходник.

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

SaveOptions используют, когда нужно явно управлять синхронизацией метаданных и параметрами результата. Поток после Save следует сбросить и закрыть до публикации. Если это MemoryStream, перед передачей читателю позицию возвращают в начало; иначе получатель увидит пустой ответ, хотя массив байтов фактически содержит документ.

В асинхронном веб-коде сама PDF-операция может оставаться синхронной и занимать процессор. Не следует оборачивать каждую функцию в бесконтрольный Task.Run. Тяжёлые задания отправляют в ограниченную очередь фоновых работ, а HTTP-запрос возвращает идентификатор. Это защищает пул потоков и позволяет отменять, повторять и измерять обработку.

Геометрия страницы, рамки и преобразования

У страницы PDF есть несколько областей, и видимая часть может не совпадать с полным физическим листом. MediaBox задаёт общий размер, CropBox — область показа, а печатные и технологические рамки могут использоваться в издательском процессе. Перед размещением штампа приложение должно выяснить, относительно какой рамки вычисляются координаты, иначе объект окажется за пределами видимой области.

Положение прямоугольного элемента удобно рассчитывать функцией, которая принимает ширину и высоту выбранной области, поля и привязку. Например, правый верхний штамп получает X как ширину страницы минус правое поле и ширину штампа, а Y — высоту страницы минус верхнее поле и высоту штампа. Такое вычисление переносится между A4 и Letter, тогда как фиксированные координаты — нет.

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

Масштаб и смещение нужно объединять в предсказуемом порядке. Сначала определяют целевой прямоугольник, затем коэффициент вписывания, после этого масштабируют и вычисляют остаточные поля для центрирования. Если сначала сместить содержимое, а затем масштабировать, смещение тоже изменится и объект уйдёт с ожидаемого места.

При копировании страницы в документ с другой геометрией не требуется автоматически растягивать её до нового размера. Сохранение исходных пропорций обычно важнее полного заполнения листа. Для печатного приложения лучше добавить белые поля, чем исказить подписи, штрихкоды или схемы.

Контроль размера итогового файла

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

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

Вложения учитывают отдельно от визуального содержимого. XML электронного счёта обычно мал, а исходные изображения, офисные документы и сжатые пакеты способны увеличить PDF в несколько раз. Приложение должно иметь предельный размер каждого вложения и общий лимит пакета.

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

Размер контролируют на каждом этапе: вход, промежуточный файл и результат. Резкий рост после простой операции указывает на дублирование ресурсов или повторное растрирование страниц. Такой показатель полезно включить в автоматическое предупреждение задания.

Особенности отдельных типов полей формы

Текстовое поле может быть однострочным, многострочным, числовым или предназначенным для даты. Его виджет получает рамку, фон, шрифт, кегль и выравнивание. Для длинного значения заранее выбирают политику: уменьшать шрифт, разрешать прокрутку либо отклонять данные. Автоматическое уменьшение до нечитаемого размера формально заполняет форму, но делает документ бесполезным.

Флажок хранит состояние, которое должно соответствовать допустимому экспортному значению. Нельзя считать, что любое значение true визуально включит произвольный внешний шаблон: сначала изучают варианты состояния существующего виджета. При создании своей формы задают согласованные состояния и проверяют внешний вид включённого и выключенного флажка.

Группа переключателей представляет один логический выбор и несколько виджетов. У каждого элемента есть собственное экспортное значение, но выбранным может быть только один. Если бизнес-данные содержат неизвестный вариант, приложение не должно молча выбирать первый пункт; оно формирует ошибку валидации или оставляет поле пустым по явному правилу.

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

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

При чтении чужой формы поля могут быть вложены в группы. ToFlatEnumerable помогает получить плоскую последовательность для проверки всех значений, но при изменении нужно сохранять иерархию. Имена полей сравнивают с учётом требований шаблона; различие регистра или точка в составном имени может обозначать другой объект.

Внешний вид аннотаций и совместимость просмотрщиков

Аннотация содержит семантические свойства и appearance — сохранённое визуальное представление. Если внешний вид не сформирован или использует недоступный шрифт, разные просмотрщики могут показать объект по-разному. Для документов, которые будут открываться в браузере, Acrobat и мобильном приложении, тестируют все целевые варианты.

Граница настраивается толщиной, стилем и штриховым шаблоном; некоторые типы поддерживают эффект облака, окончания линий и выноски. Цвет заливки и прозрачность должны сохранять читаемость текста под разметкой. Для выделения выбирают полупрозрачную заливку, для редакции после применения — непрозрачную.

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

Флаг печати проверяют отдельно. Внутренняя рецензия может быть полезна на экране, но недопустима в печатной копии для клиента. Перед финальным выпуском приложение формирует отчёт по типам аннотаций и явно решает, какие удалить, применить или оставить.

Интеграция в ASP.NET, фоновые службы и контейнеры

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

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

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

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

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

Результат загружают в постоянное хранилище под новым ключом, затем одной транзакцией отмечают задание выполненным. Если сначала изменить статус, а потом загрузить файл, пользователь может получить ссылку на отсутствующий объект. Для загрузки полезно вычислить SHA-256 и сохранить его рядом с размером и количеством страниц.

Совместимость проектов .NET

Официальный пакет предоставляет сборки для .NET 8 и .NET Framework 4.6.2; более новые совместимые целевые платформы могут использовать соответствующий актив. Это позволяет применять одну предметную модель в консольных службах, ASP.NET Core, Blazor, WinForms и WPF, но интерфейс приложения и способ развертывания остаются ответственностью разработчика.

При выборе Target Framework учитывают не только формальную совместимость пакета. Окружение должно поддерживать остальные зависимости проекта, библиотеку рисования, шрифты и средства печати. Перенос старого приложения .NET Framework на современный .NET лучше проверять отдельным прототипом с реальными документами, потому что различия среды проявляются в файловых путях, шрифтах и драйверах.

Все пакеты DevExpress в одном проекте должны иметь согласованные версии зависимостей. Явная ссылка на DevExpress.Data другой поставки часто приводит к конфликту сборок или ошибке загрузки во время выполнения. Central Package Management помогает зафиксировать единый номер, а автоматическая проверка зависимостей предотвращает случайное расхождение после обновления одного проекта решения.

Публикация self-contained не отменяет внешние ресурсы: системные шрифты, очередь печати и корневые сертификаты не всегда включаются в приложение. Развёртывание проверяют на чистой машине или в чистом контейнере, а не только после установки полного набора инструментов на компьютере разработчика.

Наблюдаемость, метрики и обработка отказов

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

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

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

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

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

Сравнение DevExpress PDF Document API с аналогами

Программа	Лучше подходит для	Главное ограничение
DevExpress PDF Document API	Объектной обработки PDF в проектах .NET с формами, аннотациями, тегами и печатью	Предварительный статус API и коммерческая лицензия
iText Core	Низкоуровневой работы со стандартами PDF, подписями и сложными серверными процессами	AGPL требует открытия кода либо коммерческой лицензии
Syncfusion PDF Library	Командам, уже использующим экосистему Syncfusion на веб-, настольных и мобильных платформах .NET	Условия коммерческого или Community-лицензирования нужно проверять заранее
Aspose.PDF for .NET	Широкой конвертации, стандартам PDF/A, PDF/X, PDF/E, PDF/UA и разнородным форматам	Большой API и ограничения оценочного режима усложняют первоначальную настройку
IronPDF	Генерации PDF из HTML и CSS в приложениях .NET, где важен браузерный рендеринг	Chromium-движок увеличивает размер и требования развертывания

DevExpress рационален, когда проекту нужна типизированная модель страниц, фрагментов, форм, аннотаций и доступности в привычной экосистеме .NET. iText выбирают команды, которым нужен зрелый низкоуровневый инструментарий и подходит его модель лицензирования. Syncfusion удобен при уже принятом наборе компонентов этого производителя, Aspose — при максимально широких требованиях к стандартам и конвертации, IronPDF — когда основной вход представляет собой HTML. PDF Commander решает ручное редактирование готовых файлов и не является прямой заменой программной библиотеке.

Когда выбор DevExpress оправдан

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

Особенно полезна возможность работать с содержимым как с типизированными фрагментами. Приложение может найти текст, получить координаты совпадения, изменить формат или создать область редакции; может связать поле формы с виджетом; может построить дерево структуры и добавить в него тот же текстовый фрагмент. Такие связи трудно реализовать над инструментом, который воспринимает страницу только как изображение.

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

Рекомендуемая схема первого внедрения

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

Затем добавляют структурированный результат обработки: число страниц, список предупреждений, выполненные действия и контрольные показатели. Исключение преобразуют в понятную категорию — неверный пароль, повреждённый файл, неподдерживаемая структура, ошибка сохранения или нехватка ресурсов. Пользователю не показывают полный стек и секретные пути.

После функционального теста прогоняют набор реальных документов, измеряют время и память, проверяют Windows и целевую серверную среду. Только после этого подключают очередь, повторные попытки и пакетную обработку. Для операций редакции и доступности добавляют независимую верификацию до публикации.

Финальный критерий готовности — не факт создания файла, а воспроизводимость результата. Один и тот же вход с одной конфигурацией должен давать документ с ожидаемыми страницами, текстом, полями, метаданными и разрешениями, а контрольные тесты должны обнаруживать любое отклонение.

Контрольный список перед выдачей документа

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

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

Визуальная проверка строится на экспорте характерных страниц: первой, последней и каждой страницы, которую менял код. Изображения сравнивают с эталоном или анализируют правилами — наличие штампа в допустимой области, отсутствие обрезки и правильная ориентация. Случайная выборка недостаточна, если одна операция затронула конкретные листы.

Технические показатели включают размер, SHA-256, время обработки и перечень выполненных действий. Хеш сохраняют после окончательного закрытия потока. Если документ затем подписывается или переносится другой системой, ожидаемое изменение хеша фиксируется как отдельный этап, а не воспринимается как повреждение.

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

Итоговая практика работы

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

Надёжная реализация всегда сохраняет исходник, ограничивает недоверенный вход, освобождает ресурсы, повторно открывает выход и выполняет предметные проверки. Для формы проверяются значения и виджеты, для редакции — отсутствие исходного текста и скрытых копий, для счёта ZUGFeRD — вложенный XML и профиль, для доступности — структура и независимый валидатор.

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