HTML a PDF para .NET

Traducido por Bit Miracle. Artículo original de Sergey Bobrovsky

Actualizado el 2 de julio de 2026

Puede convertir HTML a PDF usando la biblioteca Docotic.Pdf. El complemento gratuito HtmlToPdf de la biblioteca permite convertir HTML, SVG, WEBP y otros formatos web a PDF.

Esta guía describe las funciones de HTML a PDF proporcionadas por el complemento e incluye enlaces a páginas con más detalles sobre los temas tratados.

Lo básico de HTML a PDF en C#

Necesitará el complemento HtmlToPdf, un fragmento de conversión y una clave de licencia. Puede empezar con una clave de prueba gratuita.

Instale el complemento desde NuGet

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

Esta es la forma recomendada porque gestiona automáticamente las dependencias y las actualizaciones. También puede instalar el complemento manualmente desde el archivo zip con los binarios de Docotic.Pdf, aunque es más complicado y propenso a errores.

Obtenga una clave de licencia

Para probar la biblioteca, obtenga una clave de licencia gratuita y con tiempo limitado en la página de descarga de Docotic.Pdf. Si ya compró una licencia, use el código que se le proporcionó después de la compra.

Todas las licencias de Docotic.Pdf incluyen funciones de HTML a PDF. No es necesario comprar una licencia adicional para usar el complemento.

Agregue el código de conversión

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");

En el código, reemplace el valor de marcador de posición en la llamada al método AddLicenseData con una clave de licencia válida.

Ejecute el código

El código de conversión creará un PDF a partir del código HTML de la cadena. Con las opciones de conversión predeterminadas, la salida contendrá una página tamaño A4.

La biblioteca ofrece muchas opciones para personalizar la conversión. Puede cambiar el tamaño de salida o agregar encabezados y pies de página a las páginas generadas. También es posible convertir recursos que requieren autenticación.

Lea sobre las diferentes formas de convertir HTML a PDF en el artículo dedicado, que explica cada enfoque con gran detalle.

¿Por qué Docotic.Pdf es el convertidor HTML a PDF adecuado?

La capacidad de conservar estilos y diseño durante la conversión hace que Docotic.Pdf sea la elección adecuada para producir PDFs a partir de informes HTML, facturas y otros documentos. La biblioteca genera documentos PDF con fidelidad de píxel a partir de HTML y otros formatos web como SVG. Reutilizar contenido HTML existente es fácil con la biblioteca.

El convertidor usa el motor de renderizado de Google Chrome. Esto significa el mismo nivel de compatibilidad con los estándares web que uno de los mejores navegadores web.

Puede usar Docotic.Pdf para producir PDFs a partir de diseños muy complejos con CSS moderno, JavaScript e imágenes. El diseño web adaptable también está muy bien soportado.

Resumen de la arquitectura de la API

La API de HTML a PDF solo está disponible cuando se usa Docotic.Pdf junto con el complemento HtmlToPdf gratuito.

El complemento proporciona una API solo asíncrona. La diseñamos para funcionar con controladores de eventos asincrónicos y métodos asincrónicos. Este diseño permite gestionar con elegancia tareas de larga duración, y la conversión de contenido multimedia es un ejemplo ideal de este tipo de tarea.

Versiones de .NET y compatibilidad de plataforma

La biblioteca y el complemento están destinados a .NET Standard 2.0. Esto significa que ambos son compatibles con .NET 5 hasta .NET 10. Además, también se admiten .NET Core 2.0+ y .NET Framework 4.6.1+.

Puede usar las funciones de HTML a PDF en Windows Forms, WPF, ASP.NET y aplicaciones de consola. El complemento puede ejecutarse en entornos en la nube y en contenedores Docker.

Con la ayuda del complemento, puede generar PDF a partir de HTML en entornos Windows, macOS y Linux.

¿Qué ocurre durante una conversión?

De forma predeterminada, una conversión consta de estas etapas:

1. Su código llama al método CreateAsync de la clase HtmlConverter.
2. El complemento comprueba si existe una versión apta de Google Chrome en la carpeta .local-chromium dentro del directorio de trabajo actual.
3. Si no hay una versión apta, el complemento descarga una y la descomprime en la carpeta .local-chromium.
4. Cuando su código llama al método CreatePdfAsync o CreatePdfFromStringAsync, el complemento usa Google Chrome para cargar el HTML proporcionado.
5. Cuando el contenido está listo para la conversión, el complemento indica al navegador que produzca un PDF.
6. Google Chrome genera el PDF usando las capacidades de renderizado de Chromium.
7. El complemento devuelve a su código un PdfDocument que contiene el PDF generado.

Plataformas en la nube e imágenes Docker

El complemento HtmlToPdf admite las plataformas en la nube Azure y AWS, incluidos entornos sin servidor. También puede usar la API de HTML a PDF en contenedores Docker. Esta es la lista de entornos admitidos:

• Azure: Azure Functions, Azure App Service, Azure VPS
• Amazon Web Services: AWS ECS, Amazon EC2
• Docker: contenedores Windows y Linux.

La biblioteca y el complemento admiten por completo cambios dinámicos de hardware, escalado automático y otras características de ejecución nativas de la nube.

Consulte el artículo sobre cómo ejecutar el complemento en la nube y en imágenes Docker para obtener más información.

En la mayoría de los escenarios en la nube, se requiere una licencia no vinculada. La FAQ de licencias explica cómo elegir la licencia adecuada para aplicaciones en la nube.

Cómo generar PDF a partir de una plantilla HTML

Siga estos sencillos pasos:

1. Recupere los datos de la plantilla.
2. Rellene la plantilla con los datos para producir un HTML completo.
3. Use Docotic.Pdf para convertir el HTML completo a PDF.

Los datos de la plantilla normalmente provienen de una base de datos o de una respuesta de API. Con una base de datos, puede ser un único registro o un conjunto de registros. En el caso de una API, a menudo es un objeto JSON que describe una o más entidades.

Para los ejemplos siguientes, usaré esta persona ficticia:

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

Ahora que tengo los datos, presentaré tres opciones para preparar y rellenar una plantilla HTML. En los tres casos, el HTML completo resultante será el mismo, aunque las plantillas correspondientes sean distintas.

Para convertir el HTML completo, use el código que ya proporcioné.

Marcadores de posición con nombre

Los marcadores de posición con nombre son tokens delimitados por dobles separadores que usan símbolos no alfanuméricos. Uno de los separadores más resistentes a colisiones es %%.

Aquí hay una plantilla con marcadores de posición con nombre, junto con el código que produce HTML completo a partir de ella:

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);

Usar marcadores de posición con nombre es el enfoque recomendado en la mayoría de los casos. Sin embargo, recuerde escapar cualquier valor que inserte en lugar de los marcadores de posición.

Motores de plantillas

Cuando su plantilla es muy compleja y/o requiere partes reutilizables, los marcadores de posición con nombre pueden no ser muy convenientes. En su lugar, pruebe un motor de plantillas como Handlebars.Net.

Aquí hay un ejemplo que usa una plantilla y un código diferentes, pero produce el mismo 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);

Las plantillas de Handlebars.Net no tienen lógica. Si eso le resulta demasiado restrictivo, pruebe Scriban. Ofrece condicionales, bucles, expresiones, llamadas a funciones y más.

Marcadores de posición posicionales

Son muy similares a los marcadores de posición con nombre, pero usan números de posición en lugar de nombres. Los habrá visto en llamadas al método 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);

Le sugiero no usar marcadores de posición posicionales salvo en los casos más simples. Estas son un par de razones:

• Cuando la plantilla usa un valor más de una vez, debe proporcionar ese valor varias veces en la llamada.
• Es demasiado fácil cambiar el orden en la plantilla y olvidar actualizar el código.

Convertir ASPX a PDF

Use Docotic.Pdf junto con el complemento HtmlToPdf gratuito para convertir ASPX a PDF. El proceso es sencillo:

• Proporcione una implementación del método Render que acumule el HTML generado.
• Deje que el motor de ASP.NET genere el HTML de la página ASPX ejecutando código y controles del lado del servidor.
• Convierta el HTML acumulado a PDF y devuelva el PDF en la respuesta actualizada.

Consulte el código de ejemplo para ver cómo generar un PDF a partir de una página ASPX en una aplicación ASP.NET Web Forms. La aplicación de ejemplo demuestra el proceso anterior creando una factura en formato HTML o PDF. Puede usar el mismo enfoque para producir versiones PDF de alta fidelidad de sus informes, estados de cuenta y otros documentos.

Convertir SVG a PDF

Las conversiones de SVG a PDF vectorial son posibles con el complemento HtmlToPdf para la biblioteca Docotic.Pdf. Puede usar la clase HtmlConverter como convertidor de SVG a PDF. El siguiente código C# muestra una forma de realizar la conversión:

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");

El resultado del código anterior es un PDF vectorial de alta calidad. El convertidor proporcionado por el complemento HtmlToPdf usa el ancho y el alto especificados en el SVG para determinar la relación de aspecto. Según el tamaño del SVG, el convertidor puede escalarlo proporcionalmente para ajustarlo a la página PDF.

Opciones que afectan al tamaño de salida

Para producir un PDF de un tamaño diferente, establezca el tamaño de página y/o los márgenes. El SVG convertido puede seguir escalándose proporcionalmente.

Otra opción es especificar el ancho y/o el alto del SVG en el código HTML y convertir ese HTML. En la salida, la imagen tendrá el tamaño especificado. Si el tamaño es mayor que la página PDF, algunas partes de la imagen no serán visibles.

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");

Archivo SVG a PDF

Para convertir un archivo SVG a PDF, cree un Uri de archivo y páselo al método CreatePdfAsync. Otra opción es crear un fragmento HTML con una etiqueta img y usar ese fragmento con el método CreatePdfFromStringAsync. Si usa rutas relativas en el código HTML, proporcione la URL base mediante las opciones de conversión.

Para convertir varios archivos SVG a PDF, cree un fragmento HTML que contenga varias etiquetas img y úselo con el método CreatePdfFromStringAsync. Si todos los archivos están ubicados en la misma carpeta, recomiendo usar rutas relativas en el código HTML y proporcionar la URL base.

Agregar SVG a PDF

Empiece convirtiendo el SVG a PDF usando uno de los métodos de HtmlConverter.

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

Luego puede superponer el contenido del PDF generado sobre otro documento, o combinar el documento con otro PDF.

Para superponer un SVG sobre un PDF, cree un XObject a partir de la primera página del documento convertido y dibuje ese XObject sobre una página PDF de otro documento. Así:

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");

Para combinar un SVG en un PDF, combine el documento PDF convertido con otro PDF usando uno de los enfoques de combinación disponibles.

Convertir WEBP a PDF

WebP es un formato web, así que puede convertirlo a PDF usando Docotic.Pdf con el complemento HtmlToPdf. El siguiente código C# demuestra cómo convertir de WebP a PDF con alta calidad:

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");

El código anterior no especifica atributos width ni height para la etiqueta img, pero es una buena idea incluirlos. Tenga en cuenta que si el tamaño de imagen que especifica es mayor que la página PDF, algunas partes de la imagen no serán visibles.

Dado que WebP es un formato raster, no escalará bien. Recomiendo usar imágenes con el tamaño y la resolución máximos que espere necesitar.

Para convertir un archivo WebP a PDF, use el mismo código. Si su HTML usa rutas relativas, proporcione la URL base mediante las opciones de carga. Use un Uri de archivo como URL base al convertir imágenes locales.

Convertir XML a PDF usando XSLT

Para convertir XML a PDF, primero transforme el XML en HTML usando una transformación XSLT. Luego convierta el HTML resultante a PDF usando Docotic.Pdf con el complemento HtmlToPdf.

Aquí está el código C# de conversión de XML a PDF:

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");

El código:

• Crea un objeto de transformación XSLT en la primera línea.
• Transforma el archivo XML en un documento HTML en la segunda línea.
• Convierte el resultado de la transformación (la cadena HTML) a PDF en las líneas restantes.

Veamos con más detalle los dos primeros puntos. El tercero se cubre por completo en esta sección.

Cree una transformación XSLT

El primer paso en el proceso de conversión es crear un objeto de transformación XSLT. El siguiente código demuestra cómo crear un objeto de este tipo:

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

Como su nombre indica, XslCompiledTransform compila la hoja de estilos proporcionada y produce código IL a partir de ella. Si su código necesita transformar XML a PDF en lote, reutilice el mismo objeto de transformación para mejorar el rendimiento.

Transforme XML a HTML

El segundo paso es generar HTML a partir del XML usando el objeto de transformación XSLT creado en el paso anterior.

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

El código usa XmlReader y XmlWriter porque están bien adaptados para archivos XML grandes y ayudan a mantener bajo el uso de memoria.

Código de ejemplo para la conversión de XML a PDF

Nuestro repositorio de ejemplos incluye versiones en C# y VB.NET de una aplicación de ejemplo que convierte una factura XML en un PDF. La aplicación de ejemplo contiene una factura XML de ejemplo y la hoja de estilos XSLT correspondiente.

Cuando navega a una URL que devuelve XML en un navegador moderno, el navegador puede aplicar automáticamente el XSLT asociado (si existe) para generar y mostrar HTML legible. Esto solo funciona cuando tanto los archivos XML como XSLT están alojados en el mismo servidor. Para evitar solicitudes de origen cruzado, el navegador no cargará ni aplicará la hoja de estilos cuando abra el archivo XML directamente desde el sistema de archivos local.

Compromisos y formas alternativas de crear PDF

La API de HTML a PDF no es la única forma de generar PDFs con Docotic.Pdf, y no siempre es la más eficiente. Esta sección describe las alternativas para ayudarle a elegir la opción adecuada para su escenario.

Cuándo HTML a PDF es la opción correcta

Elija el enfoque HTML a PDF cuando su equipo ya cree documentos con HTML/CSS. Especialmente si sus documentos se parecen a páginas web: facturas, órdenes de compra, certificados, recibos y similares.

El complemento HtmlToPdf permite a los equipos reutilizar plantillas HTML/CSS existentes y beneficiarse de capacidades de diseño y renderizado de alta fidelidad. Usando el complemento, la ruta hacia una salida PDF de alta calidad puede ser la más rápida.

Limitaciones que conviene tener en cuenta

La API de HTML a PDF usa el motor de renderizado HTML de Google Chrome. Este motor es potente, pero conlleva sobrecarga. Una conversión típica de HTML a PDF consume más CPU y memoria que dibujar directamente sobre el lienzo de una página PDF, por ejemplo. Esta sobrecarga puede ralentizar la generación por lotes de gran volumen.

El motor del navegador también aumenta la huella en tiempo de ejecución, lo que puede no ser deseable en imágenes Docker minimalistas o entornos restringidos. Por ejemplo, la API puede no funcionar en entornos sin servidor con límites muy estrictos de consumo de memoria y tiempo de ejecución.

Otras formas de producir PDFs en Docotic.Pdf

La biblioteca Docotic.Pdf proporciona varias otras formas de crear documentos, cada una adecuada para distintas necesidades:

• Generación directa de PDF mediante la Canvas API
  Ideal para diseños estructurados y predecibles, como entradas, etiquetas o formularios. Ofrece máximo rendimiento y control total sobre coordenadas, tipografía y colocación del contenido.

• Generación de PDF basada en plantillas
  A menudo es la mejor opción cuando trabaja con plantillas aprobadas y controladas por cumplimiento. Empieza con un PDF existente y completa campos, reemplaza marcadores de posición y adjunta documentos relacionados según sea necesario.

• Generación de PDF con la Layout API
  Proporciona bloques de construcción como páginas, contenedores, imágenes, párrafos de texto y otros elementos de diseño. Usted describe el diseño del PDF completamente en código usando una API fluida, y la biblioteca genera el PDF a partir de su diseño.

• Composición a partir de otros PDFs e imágenes
  Ofrece una forma ligera de ensamblar estados de cuenta, informes, paquetes de documentos y otros documentos a partir de PDFs e imágenes existentes. Convierte imágenes en páginas PDF, combina varios PDFs, agrega páginas o reutiliza fragmentos.

Comparación con otras soluciones HTML a PDF

Para ayudarle a elegir la biblioteca HTML a PDF adecuada para .NET, aquí tiene información sobre cómo Docotic.Pdf con el complemento HtmlToPdf se compara con otras soluciones populares para convertir HTML a PDF.

Puntos clave de la comparación

La mayoría de las soluciones basadas en navegador proporcionan renderizado de alta calidad y admiten completamente HTML, CSS y JavaScript modernos. Sin embargo, existen diferencias importantes.

Comparación detallada

Revise la información de la tabla para obtener una visión completa y sacar sus propias conclusiones.

Conclusión

Docotic.Pdf con el complemento HtmlToPdf proporciona conversiones de HTML a PDF fiables y de alta calidad junto con una API de PDF con funciones completas. La biblioteca funciona bien para generar informes PDF, facturas, recibos y otros documentos empresariales a partir de HTML, conservando una fidelidad visual píxel a píxel.

El complemento proporciona una API asíncrona de .NET que se ejecuta completamente en las instalaciones. Sus datos nunca salen de sus servidores, lo que le da control total sobre la seguridad y la privacidad.

Además de la conversión de HTML a PDF, Docotic.Pdf puede agregar protección con contraseña a los PDFs generados y firmarlos con firmas digitales, incluidas firmas habilitadas para LTV.

Puede ensamblar documentos finales mediante la combinación de varios PDFs generados. Si un PDF se vuelve demasiado grande después de la conversión de HTML o de la combinación, la biblioteca puede eliminar objetos duplicados dentro del archivo y aplicar otros métodos para reducir el tamaño del archivo. Para mejorar la experiencia de lectura, Docotic.Pdf también puede optimizar PDFs para Fast Web View (linearizar el PDF).

Siguientes pasos:

• Revise los ejemplos de código
• Explore la API de la biblioteca
• Contáctenos con preguntas o sugerencias

Preguntas frecuentes

¿Cómo elegir una biblioteca de HTML a PDF para .NET?

Antes de seleccionar una biblioteca, defina y recopile sus requisitos. Ahorrará tiempo durante la evaluación si sabe que una biblioteca candidata no puede combinar PDFs convertidos y esta función es necesaria para su solución. Consulte la sección de comparación para ver en paralelo bibliotecas populares de HTML a PDF para .NET.

¿Por qué mi HTML no se renderiza correctamente en PDF?

Si su HTML se ve correcto en Google Chrome pero no en el PDF generado, entonces revise las opciones de conversión. Asegúrese de que haya suficiente ancho para acomodar el contenido. El HTML también podría requerir ejecutar JavaScript antes de la conversión.

¿Por qué usar plantillas HTML en lugar de APIs PDF directas?

Usar plantillas HTML hace que su solución sea muy flexible en el diseño de los documentos. Puede cambiar fácilmente la apariencia de sus PDFs usando las potentes capacidades de estilo de HTML y CSS. Además, no necesita duplicar el diseño de sus documentos en línea con una API de PDF.

¿Cómo convertir ASPX a PDF?

Para convertir ASPX a PDF, deje que el motor de ASP.NET genere el HTML de la página ASPX y luego convierta ese HTML a PDF usando la biblioteca Docotic.Pdf. Hay más detalles disponibles en la sección correspondiente.

¿Cómo superponer un SVG sobre un PDF?

Para superponer un SVG sobre un PDF, genere un PDF a partir del SVG, y luego cree un XObject a partir de la primera página del documento generado. Como el XObject tiene un fondo transparente, puede colocarlo sobre una página PDF de otro documento.

¿Cómo agregar una marca de agua al PDF generado?

Para agregar una marca de agua a un documento PDF producido a partir de HTML, cree un XObject, rellénelo con el contenido de la marca de agua y luego dibuje el XObject sobre las páginas del documento. Puede usar gráficos vectoriales, imágenes y texto para la marca de agua.

¿Docotic.Pdf es mejor que wkhtmltopdf?

Docotic.Pdf admite completamente HTML, CSS y JavaScript modernos, mientras que wkhtmltopdf a menudo produce un renderizado inconsistente para documentos web modernos. Además, Docotic.Pdf ofrece APIs más allá de la conversión de HTML a PDF. Por ejemplo, la biblioteca puede firmar PDFs con firmas digitales habilitadas para LTV, mientras que wkhtmltopdf solo puede convertir HTML.