MigraDoc: возможности, версии, совместимость и практическое применение

MigraDoc — не программа для чтения PDF и не визуальный редактор документов. Это библиотека для .NET, которая позволяет приложению собрать документ из абзацев, таблиц, изображений, стилей, колонтитулов и других объектов, а затем выполнить автоматическую вёрстку и получить PDF или RTF. Такое позиционирование принципиально: MigraDoc имеет смысл оценивать как компонент разработки для отчётов, счетов, актов и других формируемых по данным документов, а не как замену Sumatra PDF, Word или Acrobat. На 15 сентября 2026 года стабильной веткой остаётся 6.2.4, а 7.0.0 Preview 1 предназначена прежде всего для проверки совместимости будущего поколения.

ПараметрСостояние
ПродуктMigraDoc Library, ранее широко употреблялось название MigraDoc Foundation
Разработчикempira Software GmbH, проект поддерживает PDFsharp Team
ТипОткрытая .NET-библиотека и высокоуровневая модель документов
Актуальная стабильная версия6.2.4 от 6 января 2026 года
Предварительная ветка7.0.0 Preview 1 от 24 марта 2026 года
Основной выводPDF и RTF
ПлатформыCore — кроссплатформенный .NET; GDI и WPF — Windows
РаспространениеNuGet и исходный код проекта PDFsharp
ЛицензияMIT, без роялти и обязательной платной редакции
Графический интерфейсОтдельного пользовательского редактора нет; работа ведётся через API в коде приложения

Скачать MigraDoc

Бесплатно
В реестре российского ПО
Чистая установка

Новейшая версия для Виндовс, macOS и Линукс. Удобный редактор PDF под российские реалии.

⬇ Скачать PDF Commander бесплатно

⬇ Скачать MigraDoc

Для обычного проекта MigraDoc получают не в виде EXE-установщика, а как NuGet-пакет. Безопасный основной канал — профиль PDFsharp Team в NuGet и официальный репозиторий PDFsharp. Для production-разработки логичным выбором на дату обзора является стабильная версия 6.2.4. Пакет PDFsharp-MigraDoc содержит Core-вариант и не зависит от Windows; PDFsharp-MigraDoc-GDI и PDFsharp-MigraDoc-WPF предназначены для Windows и используют соответствующие платформенные механизмы.

В NuGet уже опубликована 7.0.0-preview-1. Это именно предварительная версия: она отмечена как prerelease, а документация проекта рекомендует использовать последнюю стабильную сборку в рабочем коде и параллельно проверять будущие preview-версии на совместимость. Поэтому установка preview оправдана для тестовой ветки, миграционного стенда или проверки собственных расширений, но не должна автоматически заменять 6.2.4 в production.

Что такое MigraDoc

В актуальной документации продукт называется MigraDoc Library. Разработчик отдельно поясняет терминологию: MigraDoc — семейство связанных инструментов empira Software, а рассматриваемый здесь продукт представляет собой .NET-библиотеку моделирования и рендеринга документов на базе MigraDoc DOM. Прежнее имя MigraDoc Foundation встречается в старых материалах и пакетах, но для современной ветки разработчик использует название MigraDoc Library.

PDFsharp и MigraDoc связаны, но не тождественны. PDFsharp даёт более низкоуровневый доступ к PDF и умеет работать с существующими PDF-документами, а MigraDoc строит новый документ из высокоуровневых объектов и использует PDFsharp при выводе в PDF. Если требуется изменить уже существующий PDF, объединить страницы или выполнить низкоуровневую графическую операцию, задача обычно относится к PDFsharp либо к полноценному редактору наподобие Adobe Acrobat Pro, а не к DOM MigraDoc.

Хронология развития и поддержки

Современная линия MigraDoc заметно отличается от поколения 1.x. Ветку 1.5 разработчик оставил доступной, но не поддерживает как актуальную основу. С версии 6.0 Core-сборка перестала быть фактически привязана к Windows и получила возможность работать на Linux, macOS и других платформах, поддерживаемых .NET. Одновременно была переработана объектная модель и ускорены отдельные операции, в том числе рендеринг больших таблиц.

В 6.1 проект расширил multi-targeting и продолжил дорабатывать обработку шрифтов и изображений. В 6.2 для Windows вернули Preview user control в GDI-сборке, убрали часть жёстко заданных имён шрифтов и исправили известную проблему бесконечного цикла в PDF-renderer. В 6.2.3 появились таргеты .NET 9 и .NET 10; сборка перестала компилироваться непосредственно под снятый с поддержки .NET 6, хотя пакет благодаря совместимым целевым платформам по-прежнему может использоваться приложениями на .NET 6.

Версия 6.2.4 исправила утечку памяти, появившуюся в 6.2.3: после рендеринга PDF библиотека больше не удерживает ссылку на последний MigraDoc Document. В марте 2026 года опубликована 7.0.0 Preview 1. Её цель — ранняя проверка совместимости, исправления и подготовка следующей ветки; переход с 6.x на 7 требует перекомпиляции. Это делает 6.2.4 рациональной базой для стабильной эксплуатации, а 7.0.0 Preview 1 — отдельной тестовой траекторией.

Основные функции MigraDoc

Объектная модель и автоматическая вёрстка

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

Текст, секции и управление страницами

Абзацы поддерживают форматированный текст, отступы, интервалы, выравнивание, границы, заливку, табуляцию и параметры управления переносом. Секции задают структуру и параметры страницы, причём новая секция начинает новую страницу. Для сложной разбивки доступны ручные разрывы, KeepWithNext, KeepTogether, WidowControl и настройки начала секции на чётной или нечётной странице. Колонтитулы могут содержать не только текст, но и таблицы, изображения, текстовые фреймы и диаграммы.

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

Таблицы, изображения и диаграммы

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

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

PDF и RTF как два разных результата

Надпись «Word» в обзорном списке возможностей не означает нативный экспорт DOCX. Документированный RTF-renderer создаёт RTF, который открывается и редактируется в Microsoft Word и других совместимых редакторах. Если рабочий процесс требует именно DOCX как контрактный формат, MigraDoc нельзя считать прямым DOCX-генератором.

Связка с PDFsharp

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

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

MigraDoc не является универсальным конвертером входных документов. Он не открывает DOCX или HTML как готовый макет для автоматического преобразования в PDF и не служит визуальным редактором существующих PDF. Для конвертации HTML/RTF в PDF «из коробки» документация PDFsharp также не обещает готового конвертера. Исходные данные требуется самостоятельно преобразовать в объекты DOM либо использовать отдельный слой импорта.

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

Интерфейс и удобство использования

У MigraDoc нет собственного интерфейса в смысле оконного редактора с лентой, панелью миниатюр или визуальным холстом. Рабочая среда — IDE разработчика и API библиотеки. В Visual Studio публичные классы и методы снабжены XML-документацией, поэтому IntelliSense помогает изучать модель непосредственно в коде. Официальные примеры показывают создание Document, настройку стилей, добавление секций и содержимого, затем отдельный этап рендеринга. Отдельного языка интерфейса у библиотеки нет; ресурсные сообщения актуальной линии проекта оставлены на US English.

В Windows-ветках присутствуют компоненты предварительного просмотра, а в 6.2 разработчик вернул Preview user control для GDI и добавил соответствующие примеры для GDI/WPF. Но это не самостоятельный редактор MigraDoc: компонент нужен разработчику для встраивания предпросмотра в приложение или образец. Финальную проверку PDF всё равно разумно делать обычным PDF-просмотрщиком.

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

Поддерживаемые форматы и совместимость

Вывод и сериализация

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

К нативному импорту офисных документов MigraDoc не относится. Нет основания ожидать, что библиотека откроет DOCX, ODT или существующий PDF и восстановит из него MigraDoc DOM. Если требуется визуально редактировать ODT/DOCX и экспортировать результат в PDF, ближе по задаче LibreOffice Writer. MigraDoc решает обратную задачу: приложение знает данные и программно создаёт документ.

Изображения и шрифты

Для Core-сборки PDFsharp, от которой зависит PDF-вывод MigraDoc, официально перечислены JPEG, PNG и Windows BMP; другие растры рекомендуется заранее конвертировать в BMP или PNG. GDI и WPF используют Windows-механизмы импорта изображений и поэтому имеют другой набор возможностей. При переносе серверного приложения между Windows и Linux не следует предполагать полную идентичность поведения всех исходных графических файлов без проверки.

Шрифты — более критичная часть кроссплатформенности. В production разработчики рекомендуют собственный IFontResolver, который гарантированно отдаёт все необходимые шрифты. GDI/WPF обычно могут обращаться к установленным Windows-шрифтам, но даже на Windows-сервере доступ к системной папке может быть ограничен. В Core на Linux и macOS переносимость надёжнее строить на явно поставляемом наборе шрифтов, а не на предположении, что нужное семейство установлено.

.NET и операционные системы

Стабильный пакет PDFsharp-MigraDoc 6.2.4 публикует целевые сборки net8.0, net9.0, net10.0 и netstandard2.0. NuGet указывает совместимость пакета с приложениями .NET 6 и выше. Core-пакет не зависит от Windows и рассчитан на кроссплатформенное применение, включая Linux и macOS. Windows-варианты GDI и WPF имеют целевые платформы net8.0-windows, net9.0-windows, net10.0-windows и net462.

Паспорт обратимости операций

ЭтапЧто можно изменитьЧто теряется или фиксируется
Исходные данные и кодМожно полностью перестроить документ, стили и правила вёрсткиНичего, если данные и шаблон хранятся отдельно и версионируются
MigraDoc DOM до рендерингаМожно добавлять и менять объекты, параметры секций, стили и содержимоеОкончательные страницы ещё не рассчитаны
После flatteningОбъекты доступны, но вычисленные значения стилей уже разложены по элементамПоследующие изменения и наследование следует оценивать осторожно
PDFМожно постобрабатывать средствами PDFsharp или другого PDF-инструментаPDF не является обратимой копией MigraDoc DOM; исходная семантика шаблона не восстанавливается автоматически
RTFПользователь может редактировать текст и оформление в совместимом редактореТочная пагинация зависит от приложения просмотра и может отличаться от PDF

Производительность и стабильность

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

В версии 6.2.4 исправлена конкретная регрессия 6.2.3, при которой после PDF-рендеринга сохранялась ссылка на последний MigraDoc Document. Исправление особенно значимо для долгоживущих сервисов, регулярно формирующих документы. Поэтому использование 6.2.4 вместо 6.2.3 оправдано не только общим правилом «брать последнюю стабильную», но и конкретным исправлением управления памятью.

Лицензирование и версии

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

У MigraDoc нет отдельной «бесплатной редакции» с урезанными функциями, платной Pro-версии или временного trial, после которого генерация прекращается. Никакая активация для MIT-библиотеки не нужна. Платным может быть профессиональное сопровождение, консультации или заказная работа у команды PDFsharp, но это дополнительная услуга, а не условие использования базовой библиотеки.

Системные требования

Core

PDFsharp-MigraDoc 6.2.4 содержит таргеты net8.0, net9.0, net10.0 и netstandard2.0; NuGet сообщает, что пакет можно использовать в приложениях .NET 6 и выше. Core не зависит от Windows и предназначен для систем, на которых работает совместимый .NET, включая Windows, Linux и macOS. Для воспроизводимого PDF-вывода необходимо обеспечить доступ ко всем используемым шрифтам через FontResolver.

GDI и WPF

PDFsharp-MigraDoc-GDI и PDFsharp-MigraDoc-WPF — Windows-ориентированные пакеты. Для стабильной ветки заявлены net8.0-windows, net9.0-windows, net10.0-windows и .NET Framework 4.6.2. Выбор между ними должен соответствовать стеку самого приложения. Устанавливать WPF-вариант в кроссплатформенный backend только ради MigraDoc нецелесообразно: Core специально существует для независимости от Windows.

Что официально не нормируется

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

Карта критических зависимостей

• PDFsharp. PDF-рендеринг MigraDoc опирается на PDFsharp, поэтому версия зависимого пакета влияет на исправления PDF, шифрование, изображения и совместимость.

• .NET runtime и выбранный target framework. Core рассчитан на переносимость, GDI/WPF — на Windows. Несовпадение варианта библиотеки и целевой ОС следует отсекать ещё на уровне проекта.

• Шрифты. Для одинаковой пагинации и метрик текста приложение должно предсказуемо разрешать нужные гарнитуры. Собственный FontResolver снижает зависимость от окружения.

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

• NuGet или локальный кэш пакетов. Интернет обычно нужен для первоначального получения зависимости, но сама генерация документа выполняется библиотекой внутри приложения и не требует облачного сервиса MigraDoc.

• Программа проверки результата. Для PDF нужен обычный viewer, для RTF — совместимый текстовый процессор. Это не runtime-зависимость библиотеки, но обязательная часть контроля качества.

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

Преимущества и недостатки MigraDoc

Плюсы и минусы

• Высокоуровневая объектная модель: абзацы, стили, секции и таблицы обычно удобнее ручного расчёта координат PDF.

• Автоматические переносы страниц и наследование стилей уменьшают объём шаблонного кода для многостраничных документов.

• PDF и RTF формируются из одной модели, что удобно, когда нужен фиксированный и редактируемый варианты результата.

• Core-сборка пригодна для кроссплатформенных .NET-сервисов, а GDI/WPF остаются для Windows-сценариев.

• MIT позволяет использовать библиотеку в закрытых коммерческих приложениях без роялти.

• Интеграция с PDFsharp даёт путь к дополнительным PDF-операциям после высокоуровневой вёрстки.

• Проект активно поддерживается: в 2026 году вышли стабильная 6.2.4 и preview будущей 7-й ветки.

Минусы

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

• Нет нативного DOCX-экспорта; редактируемый офисный результат представлен RTF.

• Нет универсального импорта HTML, DOCX или существующего PDF в MigraDoc DOM.

• Кроссплатформенная генерация требует дисциплины со шрифтами и часто собственного FontResolver.

• Некоторые элементы и эффекты отличаются между PDF и RTF; например, часть табличного оформления доступна только в PDF.

• Класс Footnote существует, но прямой PDF-рендеринг сносок официально пока не поддерживается.

• Для низкоуровневой модификации готового PDF всё равно приходится переходить к PDFsharp или другому PDF-SDK.

Сравнение с аналогами

РешениеОсновная рольПодход к макетуЛицензированиеКогда выбирать
MigraDocГенерация PDF и RTF в .NETDOM, стили, поток текста, автоматическая пагинацияMITОтчёты, счета и документы из структурированных данных, особенно когда нужен RTF наряду с PDF
QuestPDFCode-first генерация PDF в .NETДекларативная компоновка в кодеВ 2026 году Community License бесплатна для подходящих категорий, включая бизнес с годовой выручкой ниже 1 млн долларов; остальные используют коммерческие условияКогда нужен современный PDF-ориентированный API и RTF не требуется
iText CoreШирокая PDF-разработка и обработка PDFНизко- и высокоуровневые PDF APIAGPL либо коммерческая лицензияКогда важны глубокие PDF-функции, обработка существующих файлов и есть подходящая лицензионная модель
LibreOffice WriterИнтерактивное создание и редактирование документовГрафический текстовый процессорСвободное ПОКогда документ формирует человек и нужен полноценный визуальный редактор вместо программного API
Sumatra PDFПросмотр готовых документов в WindowsЧтение PDF и других форматовБесплатное ПО с открытым исходным кодомКогда PDF уже создан и его нужно быстро открыть, искать текст, печатать или читать

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

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

Инструкция по установке

Core-пакет для кроссплатформенного проекта

1. Проверьте target framework проекта и выберите стабильную 6.2.4, если нет отдельной задачи тестировать MigraDoc 7.

2. В корне .NET-проекта добавьте NuGet-зависимость командой dotnet add package PDFsharp-MigraDoc —version 6.2.4 либо через менеджер NuGet IDE.

3. Убедитесь, что в файле проекта появилась ссылка на PDFsharp-MigraDoc нужной версии и восстановление зависимостей завершилось без конфликтов.

4. Для production заранее определите набор шрифтов и реализацию FontResolver, особенно если код будет работать на Linux или macOS.

5. Создайте минимальный Document, добавьте Section и Paragraph, передайте документ PdfDocumentRenderer, выполните RenderDocument и сохраните PDF.

6. Откройте полученный PDF обычным просмотрщиком и проверьте шрифт, переносы строк, поля страницы и отсутствие placeholder вместо изображений.

GDI или WPF на Windows

Если приложение само построено на Windows-стеке и нужны соответствующие возможности, вместо Core выбирают PDFsharp-MigraDoc-GDI или PDFsharp-MigraDoc-WPF. Принцип установки такой же: добавляется конкретный NuGet-пакет 6.2.4, после чего код генерации использует API MigraDoc. Смешивать несколько вариантов без явной необходимости не стоит: это усложняет зависимости и диагностику.

Первый запуск без ложной уверенности

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

Безопасное удаление

Если MigraDoc больше не нужен, удалите ровно тот пакет, который был добавлен: например, dotnet remove package PDFsharp-MigraDoc для Core-варианта. Затем выполните восстановление зависимостей и сборку проекта. Если PDFsharp использовался только транзитивно через MigraDoc, менеджер пакетов уберёт лишнюю зависимость автоматически; если PDFsharp указан напрямую или нужен другому коду, удалять его отдельно без анализа зависимостей нельзя.

Практические кейсы

Счёт или акт из бизнес-данных

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

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

Многостраничный отчёт с большой таблицей

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

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

Защищённый PDF с паролем

Цель. Сгенерировать документ MigraDoc и затем применить PDF-шифрование. Подготовка. Разделите этапы компоновки и безопасности. Действия. Сначала выполните RenderDocument, получите связанный PdfDocument, настройте SecuritySettings и метод шифрования средствами PDFsharp, только после этого сохраните файл. Такая последовательность соответствует официальной схеме интеграции MigraDoc с PDFsharp.

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

Кроссплатформенный серверный генератор

Цель. Запускать одинаковый шаблон в контейнере Linux и на компьютере разработчика. Подготовка. Выберите Core, положите допустимые шрифты рядом с приложением либо в другой контролируемый ресурс и реализуйте FontResolver. Все изображения приведите к форматам, гарантированно поддерживаемым Core.

Действия. Не полагайтесь на случайно установленные системные шрифты. Используйте одинаковые версии пакетов и один набор ресурсов в локальной и production-среде. Задайте WorkingDirectory или используйте абсолютные/контролируемые пути к изображениям. Проверка. Сравните PDF по ключевым страницам и метрикам: количество страниц, переносы заголовков и таблиц, отсутствие подмены шрифтов. Ограничение. Различия в ресурсах окружения способны изменить макет даже при одинаковом C#-коде.

Контроль перед сохранением и передачей

• Проверьте, что входные данные относятся к нужному документу и версии шаблона.

• Убедитесь, что все шрифты разрешены ожидаемым FontResolver и не произошла незаметная подмена гарнитуры.

• Просмотрите страницы с самыми длинными таблицами, заголовками и текстовыми блоками.

• Проверьте повторяемые заголовки таблиц, колонтитулы, нумерацию и внутренние ссылки.

• Найдите placeholder отсутствующих изображений; в 6.2.4 он показывает путь к проблемному ресурсу.

• Если выпускаются PDF и RTF, сравнивайте содержание, а не точную пагинацию.

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

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

Часто задаваемые вопросы

Нужно ли устанавливать Microsoft Word или Adobe Acrobat на сервер?

Для создания PDF — нет: MigraDoc и PDFsharp выполняют генерацию внутри .NET-приложения. Word нужен только если вы хотите открывать и редактировать полученный RTF именно в Word, а PDF-reader — для визуального контроля готового файла, но не для самого рендеринга.

Можно ли использовать MigraDoc в веб-приложении или контейнере Linux?

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

Что происходит, если MigraDoc не находит изображение?

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

Можно ли использовать относительные пути к изображениям?

Да. PdfDocumentRenderer и RtfDocumentRenderer используют WorkingDirectory как базовый каталог для относительных путей и сохранения. Если WorkingDirectory не задан для PDF-renderer, действует рабочий каталог приложения; для RTF рабочий каталог передаётся renderer явно.

Нужен ли FontResolver, если создаётся только RTF?

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

Можно ли добавить в PDF то, чего нет в высокоуровневом DOM MigraDoc?

Да. После рендеринга доступен PDFsharp PdfDocument, к которому можно применить низкоуровневые операции и затем сохранить результат. Это штатная схема для функций, выходящих за рамки MigraDoc, например дополнительной графики или настроек PDF-защиты.

Вывод

Не стоит выбирать MigraDoc как готовый редактор PDF, просмотрщик, HTML-конвертер или DOCX-движок. Если документ создаёт человек в интерфейсе, лучше офисный редактор; если нужно глубоко менять существующий PDF, ближе PDFsharp, iText или специализированный редактор; если требуется только чтение готовых файлов, достаточно Sumatra PDF или другого reader. Наиболее естественная ниша MigraDoc — контролируемая серверная или настольная генерация документов из данных, где шаблон выражается кодом и должен воспроизводиться без ручной вёрстки.


Ваш адрес email не будет опубликован. Обязательные поля помечены *