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 URLdata:o imágenes subidas a tu cuenta. @importy@font-facese 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
httpsy 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.
Sigue leyendo
Código e integraciones
Generar un PDF en ASP.NET Core: MVC, Razor Pages y minimal APIs
Convierte una vista Razor en PDF en ASP.NET Core con una llamada a la API: renderizador de vistas, vista lista para imprimir, acción MVC y handler de Razor Pages.
3 min de lectura
Código e integraciones
Generador de informes PDF en C#: tabla paginada con totales
Crea un informe PDF en C# a partir de una lista de objetos: tabla con la cabecera repetida en cada página, total, números de página y recuento de páginas.
3 min de lectura
Código e integraciones
Guardar un PDF en C#: en disco, como descarga o en blob storage
Guarda el PDF que devuelve una llamada de renderizado en C#: escríbelo en disco, envíalo como descarga en ASP.NET Core, usa un enlace firmado o súbelo al storage.
2 min de lectura
Código e integraciones
Generar miles de PDF en C#: ritmo, 429 y reintentos seguros
Genera un lote de PDF en C# sin avalancha de errores 429: controla el ritmo, repite solo lo seguro, reanuda una ejecución parada y para si se acaban los créditos.
3 min de lectura