Generar un PDF en ASP.NET Core: MVC, Razor Pages y minimal APIs
Publicado el 3 min de lectura
En ASP.NET Core ya tienes una buena forma de describir un documento: una vista Razor. El paso que falta es convertir lo que produce la vista en un PDF sin llevar un navegador a tu despliegue. Esta guía renderiza la vista a una cadena HTML y la envía a la API de rustedf.cloud, de modo que el mismo código sirve para una acción MVC, un handler de Razor Pages y un endpoint de minimal API.
Se apoya en el cliente tipado de la guía de C# y ASP.NET Core, que envía una plantilla guardada y sus datos. Aquí el diseño se queda en tu proyecto, como una vista.
Renderiza una vista a una cadena
Añade un servicio pequeño que ejecute una vista y devuelva su HTML:
using Microsoft.AspNetCore.Http;using Microsoft.AspNetCore.Mvc;using Microsoft.AspNetCore.Mvc.Abstractions;using Microsoft.AspNetCore.Mvc.ModelBinding;using Microsoft.AspNetCore.Mvc.Razor;using Microsoft.AspNetCore.Mvc.Rendering;using Microsoft.AspNetCore.Mvc.ViewFeatures;using Microsoft.AspNetCore.Routing;
public sealed class ViewRenderer(IRazorViewEngine viewEngine, ITempDataProvider tempData){ public async Task<string> RenderAsync<TModel>(HttpContext http, string viewPath, TModel model) { var actionContext = new ActionContext(http, http.GetRouteData(), new ActionDescriptor());
var found = viewEngine.GetView(executingFilePath: null, viewPath, isMainPage: false); if (!found.Success) throw new InvalidOperationException($"No se encontró la vista '{viewPath}'.");
var viewData = new ViewDataDictionary<TModel>( new EmptyModelMetadataProvider(), new ModelStateDictionary()) { Model = model, };
using var writer = new StringWriter(); var context = new ViewContext( actionContext, found.View, viewData, new TempDataDictionary(http, tempData), writer, new HtmlHelperOptions());
await found.View.RenderAsync(context); return writer.ToString(); }}builder.Services.AddControllersWithViews(); // o AddRazorPages(): ambos añaden el motor de vistas Razorbuilder.Services.AddScoped<ViewRenderer>();La ruta es la del archivo completo de la vista, como ~/Views/Pdf/Invoice.cshtml, así que no
depende de qué controlador o página se esté ejecutando.
Envía el HTML a la API
Añade al cliente tipado un método que envíe HTML en lugar de un id de plantilla:
public async Task<byte[]> RenderHtmlAsync( string html, string title, CancellationToken cancellationToken = default){ // El campo html es una plantilla: {{ }} y {% %} se leerían como marcadores. if (html.Contains("{{") || html.Contains("{%")) throw new InvalidOperationException("El documento contiene sintaxis de plantilla.");
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);}La comprobación está por los datos de tu modelo. Razor escapa < y &, pero deja las llaves
tal cual, así que un nombre de cliente con {{ llegaría a la API como un marcador. Rechazar el
documento es la respuesta sencilla. Si ese texto puede aparecer legítimamente, envíalo como
data en una plantilla guardada, donde siempre se trata como texto.
Una vista hecha para el papel
Una vista para un PDF no es la página de tu sitio. No le pongas layout, coloca los estilos dentro y deja fuera los scripts:
@model InvoiceViewModel@{ Layout = null;}<style> @@page { size: A4; margin: 20mm; @@bottom-right { content: "Página " counter(page) " de " counter(pages); } } table { width: 100%; } th { text-align: left; border-bottom: 1pt solid #000; } td { padding: 3pt 0; border-bottom: 0.5pt solid #ccc; } .number { text-align: right; } tr { break-inside: avoid; }</style>
<img src="@Html.Raw(Model.LogoDataUrl)" width="120" alt="Logotipo"><h1>Factura @Model.Number</h1><p>@Model.CustomerName</p>
<table> <thead> <tr><th>Descripción</th><th class="number">Importe</th></tr> </thead> <tbody> @foreach (var line in Model.Lines) { <tr> <td>@line.Description</td> <td class="number">@line.Amount.ToString("C", Model.Culture)</td> </tr> } </tbody></table>
<p><strong>Total @Model.Total.ToString("C", Model.Culture)</strong></p>Tres cosas en ella son fáciles de equivocar:
@@page. En un archivo.cshtml,@pagees una directiva de Razor, así que una regla@de CSS necesita la@escrita dos veces. Lo mismo vale para@@bottom-right.- La imagen. El renderizador nunca descarga una dirección web, así que un logotipo no puede
ser una ruta como
/images/logo.png. Lee el archivo en tu código, conviértelo en una cadenadata:image/png;base64,…en el modelo e imprímela conHtml.Raw: la codificación normal reescribe caracteres como el+de la cadena. - Sin layout. El layout por defecto enlaza hojas de estilo y scripts. Un archivo enlazado no es lo que quieres en un documento, y JavaScript no se ejecuta.
Una acción MVC
public sealed class InvoicesController(ViewRenderer views, PdfClient pdf) : Controller{ [HttpGet("/facturas/{number}.pdf")] public async Task<IActionResult> Pdf(string number, CancellationToken cancellationToken) { var model = await LoadInvoiceAsync(number); var html = await views.RenderAsync(HttpContext, "~/Views/Pdf/Invoice.cshtml", model); var file = await pdf.RenderHtmlAsync(html, $"Factura {number}", cancellationToken); return File(file, "application/pdf", $"factura-{number}.pdf"); }}Un handler de Razor Pages y una minimal API
El servicio recibe un HttpContext, así que la misma llamada sirve donde tengas uno. En el
modelo de una Razor Page:
public async Task<IActionResult> OnGetAsync(string number){ var html = await views.RenderAsync(HttpContext, "~/Views/Pdf/Invoice.cshtml", model); return File(await pdf.RenderHtmlAsync(html, $"Factura {number}"), "application/pdf");}Y en una minimal API, que necesita el motor de vistas Razor registrado como arriba:
app.MapGet("/facturas/{number}.pdf", async ( string number, HttpContext http, ViewRenderer views, PdfClient pdf) =>{ var html = await views.RenderAsync(http, "~/Views/Pdf/Invoice.cshtml", model); return Results.File(await pdf.RenderHtmlAsync(html, $"Factura {number}"), "application/pdf");});Guarda la clave de la API en la configuración, no en una vista, y dale al HttpClient un tiempo
límite por encima del límite de tiempo de tu plan.
Lo que el renderizador no hace
Maqueta HTML y CSS para papel y no ejecuta JavaScript, así que un gráfico dibujado por un script
llega vacío. Dibújalo en el servidor como imagen, o como SVG con rect, circle y line, que
se admiten. @import y @font-face se ignoran, así que usa las fuentes que ofrece el servicio;
consulta Fuentes.
Envía el mismo HTML a POST /v1/validate mientras construyes la vista: lista lo que el servicio
no pudo usar, sin PDF y sin crédito. En las pruebas, añade "strict": true para que una vista
que empiece a usar algo no admitido falle con 422 strict_mode_rejected.
Lee HTML y CSS admitidos, Imágenes y Errores y límites. Para mantener el diseño en tu cuenta en lugar de en tu proyecto, consulta Generar con una plantilla guardada.
Sigue leyendo
Código e integraciones
Convertir una página web a PDF en C# sin navegador headless
Descarga una página con HttpClient y convierte su HTML en PDF con una llamada a la API en C#. Qué páginas admite, cuáles no y cómo comprobarlo de antemano.
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