HTML в PDF для .NET

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

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

Вы можете преобразовывать HTML в PDF с помощью библиотеки Docotic.Pdf. Бесплатная надстройка HtmlToPdf для библиотеки позволяет преобразовывать HTML, SVG, WEBP и другие веб-форматы в PDF.

В этом руководстве описаны возможности преобразования HTML в PDF, предоставляемые надстройкой, и приведены ссылки на страницы с дополнительными сведениями по рассматриваемым темам.

Основы преобразования HTML в PDF на C#

Вам понадобятся надстройка HtmlToPdf, фрагмент кода преобразования и лицензионный ключ. Можно начать с бесплатного пробного ключа.

Установка надстройки из NuGet

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

Это рекомендуемый способ, поскольку он автоматически обрабатывает зависимости и обновления. Также можно установить надстройку вручную из ZIP-архива с двоичными файлами Docotic.Pdf, хотя это сложнее и более подвержено ошибкам.

Получение лицензионного ключа

Чтобы опробовать библиотеку, получите бесплатный ограниченный по времени лицензионный ключ на странице загрузки Docotic.Pdf. Если вы уже приобрели лицензию, используйте код, который был предоставлен после покупки.

Все лицензии Docotic.Pdf включают возможности HTML в PDF. Для использования надстройки не нужно покупать дополнительную лицензию.

Добавление кода преобразования

BitMiracle.Docotic.LicenseManager.AddLicenseData("PUT-LICENSE-HERE");

using var converter = await HtmlConverter.CreateAsync();
var html = "<h1>Hello, World<h1>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

В коде замените значение-заполнитель в вызове метода AddLicenseData на действительный лицензионный ключ.

Запуск кода

Код преобразования создаст PDF из HTML-кода в строке. При параметрах преобразования по умолчанию результат будет содержать одну страницу формата A4.

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

Подробнее о разных способах преобразования HTML в PDF см. в отдельной статье, где каждый подход объясняется очень подробно.

Почему Docotic.Pdf — подходящий конвертер HTML в PDF?

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

Конвертер использует движок рендеринга Google Chrome. Это означает тот же уровень соответствия веб-стандартам, что и у одного из лучших веб-браузеров.

Docotic.Pdf можно использовать для создания PDF из очень сложных макетов с современными CSS, JavaScript и изображениями. Адаптивный веб-дизайн тоже поддерживается очень хорошо.

Обзор архитектуры API

API HTML в PDF доступен только при использовании Docotic.Pdf вместе с бесплатной надстройкой HtmlToPdf.

Надстройка предоставляет только асинхронный API. Мы разработали его для работы с асинхронными обработчиками событий и асинхронными методами. Такой подход позволяет корректно обрабатывать длительные задачи, а преобразование медиа — идеальный пример такой задачи.

Поддерживаемые версии .NET и платформы

Библиотека и надстройка нацелены на .NET Standard 2.0. Это означает совместимость с .NET 5–.NET 10. Кроме того, поддерживаются .NET Core 2.0+ и .NET Framework 4.6.1+.

Возможности HTML в PDF можно использовать в Windows Forms, WPF, ASP.NET и консольных приложениях. Надстройка может работать в облачных средах и контейнерах Docker.

С помощью надстройки можно генерировать PDF из HTML в средах Windows, macOS и Linux.

Что происходит во время преобразования?

По умолчанию преобразование состоит из следующих этапов:

1. Ваш код вызывает метод CreateAsync класса HtmlConverter.
2. Надстройка проверяет, есть ли подходящая версия Google Chrome в папке .local-chromium внутри текущего рабочего каталога.
3. Если подходящей версии нет, надстройка загружает ее и распаковывает в папку .local-chromium.
4. Когда ваш код вызывает метод CreatePdfAsync или CreatePdfFromStringAsync, надстройка использует Google Chrome для загрузки переданного HTML.
5. Когда содержимое готово к преобразованию, надстройка инструктирует браузер создать PDF.
6. Google Chrome генерирует PDF с использованием возможностей рендеринга Chromium.
7. Надстройка возвращает вашему коду PdfDocument, содержащий созданный PDF.

Облачные платформы и Docker-образы

Надстройка HtmlToPdf поддерживает облачные платформы Azure и AWS, включая безсерверные среды. Также можно использовать API HTML в PDF в контейнерах Docker. Ниже список поддерживаемых сред:

• Azure: Azure Functions, Azure App Service, Azure VPS
• Amazon Web Services: AWS ECS, Amazon EC2
• Docker: контейнеры Windows и Linux.

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

Дополнительные сведения см. в статье о запуске надстройки в облаках и в Docker-образах.

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

Как сгенерировать PDF из HTML-шаблона

Следуйте этим простым шагам:

1. Получите данные для шаблона.
2. Заполните шаблон данными, чтобы получить полный HTML.
3. Используйте Docotic.Pdf для преобразования полного HTML в PDF.

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

Для примеров ниже я буду использовать этого вымышленного человека:

var person = new
{
    Name = "Alice Johnson",
    Age = 27,
    Email = "alicej@example.com",
    Occupation = "Truck driver"
};

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

Для преобразования полного HTML используйте код, который я уже привел.

Именованные заполнители

Именованные заполнители — это токены, заключенные в двойные разделители, использующие неалфавитно-цифровые символы. Один из наиболее устойчивых к коллизиям разделителей — %%.

Вот шаблон с именованными заполнителями и код, который формирует из него полный HTML:

var template = @"<head><title>%%NAME%%'s Profile</title></head>
<body>
    <h1>%%NAME%%</h1>
    <p><strong>Age:</strong> %%AGE%%</p>
    <p><strong>Email:</strong> %%EMAIL%%</p>
    <p><strong>Occupation:</strong> %%OCCUPATION%%</p>
</body></html>";

var completeHtml = template
    .Replace("%%NAME%%", person.Name)
    .Replace("%%AGE%%", person.Age.ToString())
    .Replace("%%EMAIL%%", person.Email)
    .Replace("%%OCCUPATION%%", person.Occupation);

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

Шаблонные движки

Когда ваш шаблон очень сложный и/или требует повторно используемых частей, именованные заполнители могут быть не очень удобны. Вместо этого попробуйте шаблонный движок, например Handlebars.Net.

Вот пример, в котором используется другой шаблон и код, но создается тот же HTML:

var template = @"<head><title>{{name}}'s Profile</title></head>
<body>
    <h1>{{name}}</h1>
    <p><strong>Age:</strong> {{age}}</p>
    <p><strong>Email:</strong> {{email}}</p>
    <p><strong>Occupation:</strong> {{occupation}}</p>
</body></html>";

var compiledTemplate = Handlebars.Compile(template);
var completeHtml = compiledTemplate(person);

Шаблоны Handlebars.Net не содержат логики. Если это кажется слишком ограничительным, попробуйте Scriban. Он предоставляет условные выражения, циклы, выражения, вызовы функций и многое другое.

Позиционные заполнители

Они очень похожи на именованные заполнители, но используют номера позиций вместо имен. Вы видели их в вызовах метода string.Format.

var template = @"<head><title>{0}'s Profile</title></head>
<body>
    <h1>{1}</h1>
    <p><strong>Age:</strong> {2}</p>
    <p><strong>Email:</strong> {3}</p>
    <p><strong>Occupation:</strong> {4}</p>
</body></html>";

var completeHtml = string.Format(
    template, person.Name, person.Name,
    person.Age, person.Email, person.Occupation);

Я советую не использовать позиционные заполнители ни для чего, кроме самых простых случаев. Вот пара причин:

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

Преобразование ASPX в PDF

Используйте Docotic.Pdf вместе с бесплатной надстройкой HtmlToPdf, чтобы преобразовать ASPX в PDF. Процесс прост:

• Предоставьте реализацию метода Render, который накапливает сгенерированный HTML.
• Позвольте движку ASP.NET сгенерировать HTML для страницы ASPX, выполняя серверный код и элементы управления.
• Преобразуйте накопленный HTML в PDF и верните PDF в обновленном ответе.

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

Преобразование SVG в PDF

Преобразование SVG в векторный PDF возможно с помощью надстройки HtmlToPdf для библиотеки Docotic.Pdf. Вы можете использовать класс HtmlConverter как конвертер SVG в PDF. Следующий код C# показывает один из способов выполнить преобразование:

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/team.svg");
using var pdf = await converter.CreatePdfAsync(uri);
pdf.Save("output.pdf");

Результат приведенного выше кода — высококачественный векторный PDF. Конвертер, предоставляемый надстройкой HtmlToPdf, использует ширину и высоту, указанные в SVG, чтобы определить соотношение сторон. В зависимости от размера SVG конвертер может масштабировать SVG пропорционально, чтобы он поместился на странице PDF.

Параметры, влияющие на размер результата

Чтобы получить PDF другого размера, задайте размер страницы и/или поля. При этом преобразованный SVG все равно может масштабироваться пропорционально.

Другой вариант — указать ширину и/или высоту SVG в HTML-коде и преобразовать этот HTML. В результате изображение будет иметь заданный размер. Если размер больше страницы PDF, некоторые части изображения не будут видны.

using var converter = await HtmlConverter.CreateAsync();
var html = $"<img src='https://bitmiracle.com/images/team.svg' width='200' />";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

Файл SVG в PDF

Чтобы преобразовать файл SVG в PDF, создайте Uri файла и передайте его методу CreatePdfAsync. Другой вариант — создать HTML-фрагмент с тегом img и использовать этот фрагмент с методом CreatePdfFromStringAsync. Если в HTML-коде используются относительные пути, передайте базовый URL через параметры преобразования.

Чтобы преобразовать несколько файлов SVG в PDF, создайте HTML-фрагмент, содержащий несколько тегов img, и используйте его с методом CreatePdfFromStringAsync. Если все файлы находятся в одной папке, я рекомендую использовать в HTML-коде относительные пути и передавать базовый URL.

Добавление SVG в PDF

Начните с преобразования SVG в PDF с помощью одного из методов HtmlConverter.

using var converter = await HtmlConverter.CreateAsync();
var uri = new Uri("https://bitmiracle.com/images/quote.svg");
using var svgPdf = await converter.CreatePdfAsync(uri);

Затем вы можете либо наложить содержимое созданного PDF поверх другого документа, либо объединить документ с другим PDF.

Чтобы наложить SVG на PDF, создайте XObject из первой страницы преобразованного документа и нарисуйте этот XObject поверх страницы PDF в другом документе. Вот так:

using var pdf = new PdfDocument("some-other.pdf");
var xObj = pdf.CreateXObject(svgPdf.Pages[0]);

pdf.Pages[0].Canvas.DrawXObject(xObj, 0, 0);
pdf.Save("output.pdf");

Чтобы объединить SVG с PDF, объедините преобразованный PDF-документ с другим PDF с помощью одного из доступных подходов к объединению.

Преобразование WEBP в PDF

WebP — это веб-формат, поэтому вы можете преобразовать его в PDF с помощью Docotic.Pdf и надстройки HtmlToPdf. Следующий код C# демонстрирует, как преобразовать WebP в PDF с высоким качеством:

using var converter = await HtmlConverter.CreateAsync();
var html = $"<img src='https://bitmiracle.com/pdf-library/images/edit/reorder-pages.webp'/>";
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("output.pdf");

В приведенном выше коде для тега img не указаны атрибуты width или height, но их стоит добавить. Имейте в виду, что если заданный вами размер изображения больше страницы PDF, некоторые части изображения не будут видны.

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

Чтобы преобразовать файл WebP в PDF, используйте тот же код. Если HTML использует относительные пути, передайте базовый URL через параметры загрузки. При преобразовании локальных изображений используйте в качестве базового URL Uri файла.

Преобразование XML в PDF с помощью XSLT

Чтобы преобразовать XML в PDF, сначала преобразуйте XML в HTML с помощью преобразования XSLT. Затем преобразуйте полученный HTML в PDF с помощью Docotic.Pdf и надстройки HtmlToPdf.

Вот код преобразования XML в PDF на C#:

var transform = CreateTransform("invoice.xsl");
var html = TransformToHtml("invoice.xml", transform);

using var converter = await HtmlConverter.CreateAsync();
using var pdf = await converter.CreatePdfFromStringAsync(html);
pdf.Save("invoice.pdf");

Код:

• Создает объект преобразования XSLT на первой строке.
• Преобразует XML-файл в HTML-документ на второй строке.
• Преобразует результат преобразования (строку HTML) в PDF на оставшихся строках.

Давайте подробнее рассмотрим первые два пункта. Третий пункт полностью описан в этом разделе.

Создание преобразования XSLT

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

public static XslCompiledTransform CreateTransform(string xsltFileName)
{
    var transform = new XslCompiledTransform();
    transform.Load(xsltFileName);
    return transform;
}

Как следует из названия, XslCompiledTransform компилирует предоставленную таблицу стилей и генерирует из нее IL-код. Если вашему коду нужно пакетно преобразовывать XML в PDF, повторно используйте один и тот же объект преобразования для повышения производительности.

Преобразование XML в HTML

Второй шаг — сгенерировать HTML из XML с помощью объекта преобразования XSLT, созданного на предыдущем шаге.

public static string TransformToHtml(string xmlFileName, XslCompiledTransform transform)
{
    using var xmlReader = XmlReader.Create(xmlFileName);
    using var sw = new StringWriter();
    using var writer = XmlWriter.Create(sw, transform.OutputSettings);
    transform.Transform(xmlReader, null, writer);
    return sw.ToString();
}

Код использует XmlReader и XmlWriter, потому что они хорошо подходят для больших XML-файлов и помогают снизить потребление памяти.

Пример кода для преобразования XML в PDF

Наш репозиторий примеров содержит версии на C# и VB.NET примера приложения, которое преобразует счет XML в PDF. Приложение-пример содержит образец XML-счета и соответствующую таблицу стилей XSLT.

Когда вы переходите по URL, который возвращает XML в современном браузере, браузер может автоматически применить связанный XSLT (если он есть), чтобы сгенерировать и отобразить читаемый HTML. Это работает только тогда, когда файлы XML и XSLT размещены на одном сервере. Чтобы предотвратить межсайтовые запросы, браузер не загрузит и не применит таблицу стилей, если вы откроете XML-файл напрямую из локальной файловой системы.

Компромиссы и альтернативные способы создания PDF

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

Когда HTML в PDF — правильный выбор

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

Надстройка HtmlToPdf позволяет командам повторно использовать существующие шаблоны HTML/CSS и получать преимущества от высокоточной компоновки и возможностей рендеринга. С надстройкой путь к высококачественному PDF-результату может быть самым быстрым.

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

API HTML в PDF использует движок рендеринга HTML Google Chrome. Этот движок мощный, но он создает накладные расходы. Типичное преобразование HTML в PDF потребляет больше CPU и памяти, чем, например, прямое рисование на холсте страницы PDF. Эти накладные расходы могут замедлить пакетную генерацию больших объемов.

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

Другие способы создавать PDF в Docotic.Pdf

Библиотека Docotic.Pdf предоставляет несколько других способов создания документов, каждый из которых подходит для разных задач:

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

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

• Генерация PDF с помощью Layout API
  Предоставляет строительные блоки, такие как страницы, контейнеры, изображения, абзацы текста и другие элементы макета. Вы описываете макет PDF полностью в коде с помощью fluent API, а библиотека генерирует PDF на основе вашего макета.

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

Сравнение с другими решениями для преобразования HTML в PDF

Чтобы помочь вам выбрать подходящую библиотеку HTML в PDF для .NET, ниже приведена информация о том, как Docotic.Pdf с надстройкой HtmlToPdf сравнивается с другими популярными решениями для преобразования HTML в PDF.

Основные выводы сравнения

Большинство решений на основе браузера обеспечивают высококачественный рендеринг и полностью поддерживают современные HTML, CSS и JavaScript. Однако есть важные различия.

Подробное сравнение

Изучите информацию в таблице, чтобы получить полную картину и сделать собственные выводы.

Заключение

Docotic.Pdf с надстройкой HtmlToPdf обеспечивает надежное, высококачественное преобразование HTML в PDF вместе с полнофункциональным PDF API. Библиотека хорошо подходит для создания PDF-отчетов, счетов, квитанций и других бизнес-документов из HTML, сохраняя пиксельную точность визуального результата.

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

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

Вы можете собирать итоговые документы объединением нескольких сгенерированных PDF. Если PDF становится слишком большим после преобразования HTML или объединения, библиотека может удалить дублирующиеся объекты внутри файла и применить другие методы, чтобы уменьшить размер файла. Чтобы улучшить опыт чтения, Docotic.Pdf также может оптимизировать PDF для Fast Web View (линейризовать PDF).

Следующие шаги:

• Изучите примеры кода
• Ознакомьтесь с более широким API библиотеки
• Свяжитесь с нами с вопросами или предложениями

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

Как выбрать библиотеку для преобразования HTML в PDF для .NET?

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

Почему мой HTML некорректно отображается в PDF?

Если HTML правильно отображается в Google Chrome, но не в сгенерированном PDF, проверьте параметры преобразования. Убедитесь, что ширины достаточно для размещения содержимого. Также HTML может требовать выполнения JavaScript перед преобразованием.

Зачем использовать HTML-шаблоны вместо прямых PDF API?

Использование HTML-шаблонов делает ваше решение очень гибким в части макета документов. Вы можете легко изменить внешний вид PDF с помощью мощных возможностей стилизации HTML и CSS. Кроме того, вам не нужно дублировать дизайн ваших онлайн-документов с помощью PDF API.

Как преобразовать ASPX в PDF?

Чтобы преобразовать ASPX в PDF, позвольте движку ASP.NET сгенерировать HTML для страницы ASPX, а затем преобразуйте этот HTML в PDF с помощью библиотеки Docotic.Pdf. Подробнее см. в соответствующем разделе.

Как наложить SVG на PDF?

Чтобы наложить SVG на PDF, сгенерируйте PDF из SVG, а затем создайте XObject из первой страницы сгенерированного документа. Поскольку XObject имеет прозрачный фон, его можно разместить поверх страницы PDF в другом документе.

Как добавить водяной знак к сгенерированному PDF?

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

Лучше ли Docotic.Pdf, чем wkhtmltopdf?

Docotic.Pdf полностью поддерживает современные HTML, CSS и JavaScript, тогда как wkhtmltopdf часто дает непоследовательный результат при рендеринге современных веб-документов. Кроме того, Docotic.Pdf предоставляет API за пределами преобразования HTML в PDF. Например, библиотека может подписывать PDF цифровыми подписями с поддержкой LTV, тогда как wkhtmltopdf умеет только преобразовывать HTML.