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(); }}builder.Services.AddControllersWithViews(); // ou AddRazorPages(): os dois adicionam o motor de views Razorbuilder.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 stringdata:image/png;base64,…no modelo e imprima-a comHtml.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.
Continue lendo
Código e integrações
Converter página web em PDF em C# sem navegador headless
Busque uma página com HttpClient e transforme o HTML em PDF com uma chamada de API em C#. Quais páginas isso atende, quais não e como conferir antes de depender.
3 min de leitura
Código e integrações
Gerador de relatório PDF em C#: tabela paginada com totais
Monte um relatório em PDF em C# a partir de uma lista de objetos: tabela com cabeçalho repetido em cada página, total, número de página e contagem de páginas.
3 min de leitura
Código e integrações
Salvar PDF em C#: em disco, como download ou em blob storage
Salve o PDF devolvido por uma chamada de renderização em C#: grave em disco, envie como download no ASP.NET Core, guarde um link assinado ou suba para o storage.
2 min de leitura
Código e integrações
Gerar milhares de PDFs em C#: ritmo, 429 e novas tentativas seguras
Gere um lote de PDFs em C# sem enxurrada de erros 429: controle o ritmo, repita só o que é seguro, retome uma execução parada e pare quando os créditos acabarem.
3 min de leitura