HTML a PDF para .NET

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

Actualizado el 27 de enero de 2026

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

Esta guía describe las funciones de conversión de HTML a PDF que ofrece el complemento e incluye enlaces a páginas con información adicional sobre los temas tratados.

Los conceptos básicos de HTML a PDF en C#

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

Instalar el complemento desde NuGet

Install-Package BitMiracle.Docotic.Pdf.HtmlToPdf

Este es el método recomendado, ya que gestiona automáticamente las dependencias y actualizaciones. También puede instalar el complemento manualmente desde el archivo zip con los binarios Docotic.Pdf, aunque es más complicado y propenso a errores.

Obtener una clave de licencia

Para probar la biblioteca, obtenga una clave de licencia gratuita por tiempo limitado en Docotic.Pdf página de descarga. Si ya adquirió una licencia, use el código que recibió tras la compra.

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

Añade 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 del marcador de posición en la llamada al método AddLicenseData con una clave de licencia válida.

Ejecutar 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, el resultado contendrá una página de tamaño A4.

La biblioteca ofrece numerosas opciones para personalizar la conversión. Puede cambiar el tamaño de salida o añadir 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 maneras de convertir HTML a PDF en el artículo dedicado, que explica cada método con gran detalle.

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

La capacidad de conservar estilos y diseño durante la conversión convierte a Docotic.Pdf en la opción ideal para generar archivos PDF a partir de informes, facturas y otros documentos HTML. La biblioteca produce documentos PDF con una precisión de píxeles perfecta a partir de HTML y otros formatos web como SVG. Reutilizar contenido HTML existente es muy fácil con la biblioteca.

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

Puede usar Docotic.Pdf para generar archivos PDF a partir de diseños muy complejos con CSS, JavaScript e imágenes modernos. Además, es compatible con el diseño web adaptable.

Descripción general de la arquitectura de API

La API de HTML a PDF solo está disponible al usar Docotic.Pdf junto con el complemento gratuito HtmlToPdf.

El complemento proporciona una API exclusivamente asíncrona. La diseñamos para que funcione con controladores de eventos y métodos asíncronos. Este diseño permite gestionar con fluidez tareas de larga duración, y la conversión de medios es un ejemplo ideal de este tipo de tareas.

Versiones de .NET y compatibilidad de plataformas

La biblioteca y el complemento son compatibles con .NET Standard 2.0. Esto significa que ambos son compatibles con .NET 5 a .NET 10. Además, también son compatibles con .NET Core 2.0 y versiones posteriores y .NET Framework 4.6.1 y versiones posteriores.

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

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

¿Qué sucede durante una conversión?

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

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

Plataformas en la nube e imágenes de Docker

El complemento HtmlToPdf es compatible con las plataformas en la nube de Azure y AWS, incluidos los entornos sin servidor. También puede usar la API de HTML a PDF en contenedores Docker. A continuación, se muestra la lista de entornos compatibles:

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

La biblioteca y el complemento son totalmente compatibles con los cambios dinámicos de hardware, el escalado automático y otras funciones de entorno de ejecución nativas de la nube.

Consulte el artículo sobre la ejecución del complemento en nubes e imágenes de Docker para obtener más información.

¿Qué tipos de licencia son compatibles con las aplicaciones en la nube?

En la mayoría de los casos, necesitará una licencia sin vincular (Ultimate o Ultimate+). Una licencia de servidor también puede funcionar si el ID de hardware no cambia.

Las licencias de servidor están vinculadas al ID de hardware del servidor. Si el hardware cambia entre ejecuciones o reinicios, la licencia de servidor dejará de ser válida. Tampoco funcionará en entornos donde el número de servidores pueda cambiar dinámicamente, ya que cada servidor de producción requiere una licencia única.

Para garantizar que el ID de hardware de su servidor se mantenga constante, puede comprobar el valor de la propiedad LicenseManager.Uid. Como alternativa, puede utilizar nuestra aplicación UID generator para recuperar el mismo ID.

Cómo generar un PDF a partir de una plantilla HTML

Sigue estos sencillos pasos:

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

Los datos de plantilla suelen provenir de una base de datos o de una respuesta de API. En una base de datos, pueden ser un solo registro o un conjunto de registros. En una API, suelen ser un objeto JSON que describe una o más entidades.

Para los siguientes ejemplos, usaré a 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 completar una plantilla HTML. En los tres casos, el HTML completo resultante será el mismo, aunque las plantillas correspondientes sean diferentes.

Para convertir el HTML completo, utilice el código que ya he proporcionado.

Marcadores de posición con nombre

Los marcadores de posición con nombre son tokens encerrados entre delimitadores dobles que utilizan símbolos no alfanuméricos. Uno de los delimitadores más resistentes a las colisiones es %%.

A continuación, se muestra una plantilla con marcadores de posición con nombre, junto con el código que genera HTML completo a partir de ellos:

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

En la mayoría de los casos, se recomienda usar marcadores de posición con nombre. Sin embargo, recuerde escapar cualquier valor que inserte en lugar de marcadores de posición.

Motores de plantillas

Si su plantilla es muy compleja o requiere partes reutilizables, los marcadores de posición con nombre pueden no ser muy prácticos. En su lugar, pruebe un motor de plantillas como Handlebars.Net.

Aquí tiene un ejemplo que utiliza una plantilla y un código diferentes, pero que 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 te parece demasiado restrictivo, prueba 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 has visto en las 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);

Te sugiero que no uses marcadores de posición, excepto en casos muy sencillos. Aquí tienes un par de razones:

• Cuando la plantilla usa un valor más de una vez, debes proporcionarlo varias veces en la llamada.
• Es muy fácil cambiar el orden en la plantilla y olvidarse de actualizar el código.

Convertir ASPX a PDF

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

• Implemente el método Render que acumula el HTML generado.
• Permita que el motor ASP.NET genere el HTML para 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.

Consulta el código de ejemplo para ver cómo generar un PDF a partir de una página ASPX en una aplicación de formularios web ASP.NET. La aplicación de ejemplo muestra el proceso anterior creando una factura en formato HTML o PDF. Puedes usar el mismo método para generar versiones PDF de alta fidelidad de tus informes, extractos y otros documentos.

Convertir SVG a PDF

La conversión de SVG a PDF vectorial es posible con el complemento HtmlToPdf para la biblioteca Docotic.Pdf. Puede usar la clase HtmlConverter como conversor 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 conversor del complemento HtmlToPdf utiliza el ancho y el alto especificados en el SVG para determinar la relación de aspecto. Dependiendo del tamaño del SVG, el conversor puede escalarlo proporcionalmente para ajustarlo a la página PDF.

Opciones que afectan el tamaño de salida

Para generar un PDF de un tamaño diferente, establezca el tamaño de página o los márgenes. El SVG convertido aún puede escalarse proporcionalmente.

Otra opción es especificar el ancho o alto del SVG en el código HTML y convertirlo. En el resultado, 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 archivo Uri y páselo al método CreatePdfAsync. Otra opción es crear un fragmento HTML con la etiqueta img y usarlo con el método CreatePdfFromStringAsync. Si utiliza 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 con varias etiquetas img y úselo con el método CreatePdfFromStringAsync. Si todos los archivos se encuentran en la misma carpeta, recomiendo usar rutas relativas en el código HTML y proporcionar la URL base.

Agregar SVG a PDF

Comience convirtiendo el SVG a PDF utilizando uno de los métodos 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 fusionarlo 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. De esta manera:

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 fusionar un SVG en PDF, combine el documento PDF convertido con otro PDF usando uno de los enfoques de fusión disponibles.

Convertir WEBP a PDF

WebP es un formato web, por lo que puede convertirlo a PDF usando Docotic.Pdf con el complemento HtmlToPdf. El siguiente código C# muestra 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 los atributos width ni height para la etiqueta img, pero conviene incluirlos. Tenga en cuenta que si el tamaño de la imagen que especifica es mayor que el de la página PDF, algunas partes de la imagen no serán visibles.

Como WebP es un formato raster, no se escalará correctamente. Recomiendo usar imágenes con el tamaño y la resolución máximos que considere necesarios.

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

Convertir XML a PDF usando XSLT

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

A continuación, se muestra el código de conversión de XML a PDF en 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");

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.

Analicemos con más detalle los dos primeros puntos. El tercero se explica en detalle en esta sección.

Crear una transformación XSLT

El primer paso del proceso de conversión es crear un objeto de transformación XSLT. El siguiente código muestra cómo crear dicho objeto:

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 genera código IL a partir de ella. Si su código necesita transformar XML a PDF en bloque, reutilice el mismo objeto de transformación para mejorar el rendimiento.

Transformar XML a HTML

El segundo paso es generar HTML a partir del XML utilizando 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 utiliza XmlReader y XmlWriter porque son adecuados para archivos XML grandes y ayudan a mantener bajo el uso de memoria.

Código de muestra 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 a PDF. Esta aplicación contiene un ejemplo de factura XML y la hoja de estilos XSLT correspondiente.

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

Compensaciones y formas alternativas de crear PDF

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

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

Elija la conversión de HTML a PDF si su equipo ya crea documentos con HTML/CSS. Especialmente si sus documentos se asemejan a páginas web: facturas, órdenes de compra, certificados, recibos, etc.

El complemento HtmlToPdf permite a los equipos reutilizar plantillas HTML/CSS existentes y aprovechar las capacidades de diseño y renderizado de alta fidelidad. Con este complemento, obtener resultados PDF de alta calidad es mucho más rápido.

Limitaciones a tener en cuenta

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

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

Otras formas de producir archivos PDF en Docotic.Pdf

La biblioteca Docotic.Pdf ofrece otras formas de generar documentos, cada una adecuada a diferentes necesidades:

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

• Generación de PDF basada en plantillas
  Suele ser la mejor opción al trabajar con plantillas aprobadas y con control de cumplimiento. Se parte de un PDF existente y se rellenan campos, se reemplazan marcadores de posición y se adjuntan documentos relacionados según sea necesario.

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

• Composición a partir de otros PDF e imágenes
  Ofrece una forma sencilla de compilar extractos, informes, conjuntos de documentos y otros documentos a partir de archivos PDF e imágenes existentes. Puede convertir imágenes en páginas PDF, combinar varios PDF, añadir páginas o reutilizar fragmentos.

Comparación con otras soluciones de HTML a PDF

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

Conclusiones clave de la comparación

La mayoría de las soluciones basadas en navegador ofrecen una representación de alta calidad y son totalmente compatibles con HTML, CSS y JavaScript modernos. Sin embargo, existen diferencias importantes.

Comparación detallada

Consulte 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 ofrece conversiones de HTML a PDF fiables y de alta calidad, además de una completa API PDF. La biblioteca es ideal para generar informes, facturas, recibos y otros documentos empresariales en PDF desde HTML, conservando una fidelidad visual impecable.

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

Además de la conversión de HTML a PDF, Docotic.Pdf puede añadir protección con contraseña a los PDF generados y firmarlos con firmas digitales, incluyendo firmas con LTV habilitado.

Puede ensamblar documentos finales fusionando varios PDF generados. Si un PDF se vuelve demasiado grande después de la conversión o fusión de HTML, la biblioteca puede eliminar los 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 los PDF para Fast Web View (linealizar el PDF).

Próximos pasos:

• Revisar ejemplos de código HTML a PDF
• Explorar la API de la biblioteca
• Contáctanos si tienes preguntas o sugerencias

Preguntas frecuentes

¿Cómo elegir una biblioteca 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 fusionar archivos PDF convertidos y que esta función es necesaria para su solución. Consulte la sección de comparación para ver un análisis comparativo de las bibliotecas de HTML a PDF más populares para .NET.

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

Si tu HTML se ve correctamente en Google Chrome, pero no en el PDF generado, revisa las opciones de conversión. Asegúrate de que el ancho sea suficiente para el contenido. El HTML también podría requerir ejecutar JavaScript antes de la conversión.

¿Por qué utilizar plantillas HTML en lugar de API PDF directas?

El uso de plantillas HTML ofrece gran flexibilidad en el diseño de documentos. Puede cambiar fácilmente la apariencia de sus PDF con las potentes funciones de estilo de HTML y CSS. Además, con una API PDF, no necesita duplicar el diseño de sus documentos en línea.

¿Cómo convertir ASPX a PDF?

Para convertir ASPX a PDF, permita que el motor ASP.NET genere el HTML de la página ASPX y luego conviértalo a PDF con la biblioteca Docotic.Pdf. Encontrará más detalles en la sección correspondiente.

¿Cómo superponer un SVG en un PDF?

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

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

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

¿Es Docotic.Pdf mejor que wkhtmltopdf?

Docotic.Pdf es totalmente compatible con HTML, CSS y JavaScript modernos, mientras que wkhtmltopdf suele generar una representación inconsistente en documentos web modernos. Además, Docotic.Pdf ofrece API que van más allá de la conversión de HTML a PDF. Por ejemplo, la biblioteca puede firmar archivos PDF con firmas digitales compatibles con LTV, mientras que wkhtmltopdf solo puede convertir HTML.