rustedf.cloud
Menú

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();
}
}
Program.cs
builder.Services.AddControllersWithViews(); // o AddRazorPages(): ambos añaden el motor de vistas Razor
builder.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, @page es 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 cadena data:image/png;base64,… en el modelo e imprímela con Html.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.

← Todos los artículos