rustedf.cloud
Menu

Gerar PDF no ASP.NET Core: MVC, Razor Pages e minimal APIs

Publicado em 3 min de leitura

No ASP.NET Core você já tem uma boa forma de descrever um documento: uma view Razor. O passo que falta é transformar o que a view produz em um PDF sem levar um navegador para o seu ambiente de publicação. Este guia renderiza a view para uma string HTML e a envia à API do rustedf.cloud, então o mesmo código serve uma action MVC, um handler do Razor Pages e um endpoint de minimal API.

Ele se apoia no cliente tipado do guia de C# e ASP.NET Core, que envia um template salvo e os seus dados. Aqui o layout fica no seu projeto, como uma view.

Renderize uma view para uma string

Acrescente um serviço pequeno que executa uma view e devolve o HTML dela:

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($"A view '{viewPath}' não foi encontrada.");
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(); // ou AddRazorPages(): os dois adicionam o motor de views Razor
builder.Services.AddScoped<ViewRenderer>();

O caminho é o do arquivo completo da view, como ~/Views/Pdf/Invoice.cshtml, então não depende de qual controller ou página está em execução.

Envie o HTML à API

Acrescente ao cliente tipado um método que envia HTML em vez de um id de template:

public async Task<byte[]> RenderHtmlAsync(
string html, string title, CancellationToken cancellationToken = default)
{
// O campo html é um template: {{ }} e {% %} seriam lidos como marcadores.
if (html.Contains("{{") || html.Contains("{%"))
throw new InvalidOperationException("O documento contém sintaxe de template.");
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 ?? $"Falha na renderização ({(int)response.StatusCode})");
}
return await response.Content.ReadAsByteArrayAsync(cancellationToken);
}

A verificação existe por causa dos dados do seu modelo. O Razor escapa < e &, mas deixa as chaves em paz, então um nome de cliente com {{ chegaria à API como um marcador. Recusar o documento é a resposta simples. Se esse texto pode aparecer legitimamente, envie-o como data em um template salvo, onde ele é sempre tratado como texto.

Uma view feita para o papel

Uma view para PDF não é a página do seu site. Não use layout, coloque os estilos dentro dela e deixe os scripts de fora:

@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>Fatura @Model.Number</h1>
<p>@Model.CustomerName</p>
<table>
<thead>
<tr><th>Descrição</th><th class="number">Valor</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>

Três coisas nela são fáceis de errar:

  • @@page. Em um arquivo .cshtml, @page é uma diretiva do Razor, então uma regra @ do CSS precisa do @ escrito duas vezes. O mesmo vale para @@bottom-right.
  • A imagem. O renderizador nunca busca um endereço da web, então um logotipo não pode ser um caminho como /images/logo.png. Leia o arquivo no seu código, transforme-o em uma string data:image/png;base64,… no modelo e imprima-a com Html.Raw: a codificação normal reescreve caracteres como o + da string.
  • Sem layout. O layout padrão vincula folhas de estilo e scripts. Um arquivo vinculado não é o que você quer em um documento, e o JavaScript não é executado.

Uma action MVC

public sealed class InvoicesController(ViewRenderer views, PdfClient pdf) : Controller
{
[HttpGet("/faturas/{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, $"Fatura {number}", cancellationToken);
return File(file, "application/pdf", $"fatura-{number}.pdf");
}
}

Um handler do Razor Pages e uma minimal API

O serviço recebe um HttpContext, então a mesma chamada funciona onde você tiver um. No modelo de uma 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, $"Fatura {number}"), "application/pdf");
}

E em uma minimal API, que precisa do motor de views Razor registrado como acima:

app.MapGet("/faturas/{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, $"Fatura {number}"), "application/pdf");
});

Mantenha a chave da API na configuração, não em uma view, e dê ao HttpClient um tempo limite acima do limite de tempo do seu plano.

O que o renderizador não faz

Ele diagrama HTML e CSS para o papel e não executa JavaScript, então um gráfico desenhado por um script chega vazio. Desenhe-o no servidor como imagem, ou como SVG com rect, circle e line, que são suportados. @import e @font-face são ignorados, então use as fontes que o serviço oferece; veja Fontes.

Envie o mesmo HTML para POST /v1/validate enquanto monta a view: ele lista o que o serviço não conseguiu usar, sem PDF e sem crédito. Nos testes, acrescente "strict": true para que uma view que passe a usar algo não suportado falhe com 422 strict_mode_rejected.

Leia HTML e CSS suportados, Imagens e Erros e limites. Para manter o layout na sua conta em vez de no seu projeto, veja Gerar com um template salvo.

← Todos os posts