rustedf.cloud
Menú

Convertir una página web a PDF en C# sin navegador headless

Publicado el 3 min de lectura

Quien busca cómo convertir una página web a PDF en C# suele acabar en un navegador headless: un Chromium que descargar, actualizar y mantener en marcha en cada servidor. El renderizador de rustedf.cloud no es un navegador. Maqueta HTML y CSS para papel y lo llamas por HTTP. Eso hace la conversión corta, pero también decide qué páginas admite, así que esta guía empieza por ahí.

Qué hace y qué no hace

El renderizador lee HTML y CSS y dibuja páginas. De eso se derivan tres cosas:

  • No se ejecuta JavaScript. Una página cuyo contenido se construye en el navegador, como una aplicación de una sola página, llega como una cáscara vacía. Para esas necesitas un navegador de verdad.
  • Nunca descarga nada. Un <img> que apunta a una dirección web se omite y se informa. Las imágenes deben ser URL data: o imágenes subidas a tu cuenta.
  • @import y @font-face se ignoran. Lo que no se admite se ignora y se informa, nunca es un error, salvo que pidas el modo estricto.

Sirve para páginas que el servidor ya entrega como HTML completo: recibos, extractos, artículos, documentación, una página de tu propia aplicación hecha para imprimir. Consulta la lista completa en HTML y CSS admitidos.

Descarga la página, envía el HTML

Añade al cliente tipado de la guía de C# y ASP.NET Core un método que envía HTML directamente:

public async Task<byte[]> RenderHtmlAsync(
string html, string title, CancellationToken cancellationToken = default)
{
using var response = await http.PostAsJsonAsync(
"v1/render", new { html, title }, cancellationToken);
if (!response.IsSuccessStatusCode)
{
var body = await response.Content.ReadFromJsonAsync<ErrorBody>(cancellationToken);
throw new InvalidOperationException(
body?.Error?.Message ?? $"Falló el renderizado ({(int)response.StatusCode})");
}
return await response.Content.ReadAsByteArrayAsync(cancellationToken);
}

Después descarga la página y renderiza lo que llegó:

public sealed class PageToPdf(HttpClient fetcher, PdfClient pdf)
{
public async Task<byte[]> ConvertAsync(Uri page, CancellationToken cancellationToken = default)
{
var html = await fetcher.GetStringAsync(page, cancellationToken);
// El campo html es una plantilla: {{ }} y {% %} se leen como marcadores.
if (html.Contains("{{") || html.Contains("{%"))
throw new InvalidOperationException("La página usa sintaxis de plantilla propia.");
return await pdf.RenderHtmlAsync(html, page.Host, cancellationToken);
}
}

La comprobación importa. El campo html es una plantilla, así que una página que contenga {{ o {%, por ejemplo un fragmento de código o la cáscara de un framework de front-end, se leería como marcadores. Cuando tu HTML ya es definitivo y no tiene ninguno, envíalo tal cual y deja data fuera.

Imágenes

Las imágenes de una página suelen apuntar a direcciones web, y esas se omiten. Descárgalas tú y embébelas como URL data: antes de enviar el HTML:

private static readonly Regex ImageSource =
new("""<img\b[^>]*?\bsrc="(?<src>[^"]+)""", RegexOptions.IgnoreCase);
private async Task<string> InlineImagesAsync(
string html, Uri page, CancellationToken cancellationToken)
{
var sources = ImageSource.Matches(html).Select(m => m.Groups["src"].Value).Distinct();
foreach (var source in sources)
{
if (source.StartsWith("data:")) continue;
using var response = await fetcher.GetAsync(new Uri(page, source), cancellationToken);
var type = response.Content.Headers.ContentType?.MediaType;
if (!response.IsSuccessStatusCode || type is not ("image/png" or "image/jpeg")) continue;
var bytes = await response.Content.ReadAsByteArrayAsync(cancellationToken);
html = html.Replace($"\"{source}\"", $"\"data:{type};base64,{Convert.ToBase64String(bytes)}\"");
}
return html;
}

Llámalo entre la descarga y el renderizado. Solo cargan PNG y JPEG, y las imágenes muy grandes o de resolución muy alta se rechazan con un aviso en lugar de ralentizar el renderizado. Una expresión regular basta para HTML sencillo; para páginas desordenadas, lee el HTML con un analizador como AngleSharp. Un logotipo que usas en todos los documentos es mejor subirlo una vez y referenciarlo como asset:<id>; consulta Imágenes.

Comprueba antes de depender de ello

Envía el mismo cuerpo a POST /v1/validate. Renderiza la página, devuelve la lista de lo que el servicio no pudo usar y no devuelve PDF ni consume crédito.

using var check = await http.PostAsJsonAsync("v1/validate", new { html, title }, cancellationToken);
Console.WriteLine(await check.Content.ReadAsStringAsync(cancellationToken));

Una entrada como ImageLoadFailed o UnsupportedProperty te dice qué perdió la página. En tus pruebas, añade "strict": true al renderizado para que una página que use algo no admitido falle con 422 strict_mode_rejected y la lista de lo que usó.

Cuando la dirección la pone un usuario

Quien hace la petición a la página es tu servidor, así que la dirección es un riesgo de tu código, no del renderizador: el servicio nunca descarga una dirección que venga de una plantilla, y es a propósito. Si un usuario puede escribir la dirección:

  • acepta solo https y comprueba el host contra una lista de permitidos;
  • desactiva las redirecciones automáticas (AllowAutoRedirect = false) o comprueba adónde lleva cada una, para que una dirección pública no te mande a una interna;
  • fija un tiempo límite y un tamaño máximo de respuesta en el HttpClient.

Lee Generar con HTML directo, Validar un documento y Errores y límites.

← Todos los artículos