Como gerar PDF a partir de HTML em C# e ASP.NET Core
Publicado em 3 min de leitura
No .NET, transformar HTML em PDF costuma significar adicionar uma biblioteca de renderização e as
peças nativas de que ela depende a cada ambiente em que você publica. Com uma API, é uma
requisição HTTP, e o HttpClient já faz isso. Este guia mostra um cliente tipado pequeno e um
endpoint do ASP.NET Core que devolve o arquivo, com a API do rustedf.cloud.
Um cliente tipado
using System.Net.Http.Json;
public sealed class PdfClient(HttpClient http){ public async Task<byte[]> RenderAsync( string templateId, Dictionary<string, object?> data, string locale = "pt-BR", CancellationToken cancellationToken = default) { using var response = await http.PostAsJsonAsync( "v1/render", new { template_id = templateId, locale, data }, cancellationToken);
if (!response.IsSuccessStatusCode) { var body = await response.Content.ReadFromJsonAsync<ErrorBody>(cancellationToken); throw new InvalidOperationException( body?.Error?.Message ?? $"Falha ao gerar ({(int)response.StatusCode})"); }
return await response.Content.ReadAsByteArrayAsync(cancellationToken); }}
public sealed record ErrorBody(ErrorDetail? Error);public sealed record ErrorDetail(string? Code, string? Message);Uma resposta bem-sucedida é o próprio PDF, então os bytes são o arquivo. Em uma falha, o corpo é um
JSON com um code estável e uma message.
Monte o data como um dicionário. O System.Text.Json renomeia as propriedades de uma classe ou
de um objeto anônimo (NomeDoCliente vira nomeDoCliente), e as chaves do seu template precisam
bater exatamente. As chaves de um dicionário ficam como você escreveu.
Registre e sirva um PDF
using System.Net.Http.Headers;
builder.Services.AddHttpClient<PdfClient>(client =>{ client.BaseAddress = new Uri("https://api.rustedf.com/"); client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", builder.Configuration["Rustedf:Key"]); client.Timeout = TimeSpan.FromSeconds(40);});
app.MapGet("/faturas/{numero}.pdf", async (string numero, PdfClient pdf) =>{ var data = new Dictionary<string, object?> { ["number"] = numero, ["customer"] = new Dictionary<string, object?> { ["name"] = "Ana Souza" }, ["total"] = "2040.50", }; var arquivo = await pdf.RenderAsync(builder.Configuration["Rustedf:InvoiceTemplate"]!, data, "pt-BR"); return Results.File(arquivo, "application/pdf");});Guarde a chave na configuração, em um cofre de segredos ou em uma variável de ambiente
(Rustedf__Key), nunca em uma view nem no navegador. Defina o tempo limite acima do limite do seu
plano, para que a sua requisição não desista antes do serviço.
Para enviar HTML em vez do id de um template salvo, use uma propriedade html no lugar de
template_id. Passe tudo o que um usuário digitou por data, e não dentro da string de HTML: os
valores em data são escapados, e o próprio HTML é lido como um template.
Tentar de novo quando o serviço está ocupado
Um 429 (limite de requisições) ou um 503 (ocupado) traz um cabeçalho Retry-After. Uma geração
que falha não custa crédito, então tentar de novo é seguro.
if (response.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable){ var espera = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(2); await Task.Delay(espera, cancellationToken); // envie a requisição de novo, um número limitado de vezes}Erros que vale tratar
| Status | code |
O que fazer |
|---|---|---|
| 401 | unauthorized |
A chave está ausente, errada ou revogada. |
| 402 | insufficient_credits |
Os créditos acabaram. Nada foi gerado. |
| 422 | invalid_template |
O template ou os dados falharam. Leia a message. |
| 429 | rate_limited |
Espere o Retry-After e tente de novo. |
| 503 | busy |
O serviço está ocupado. Espere o Retry-After e tente de novo. |
| 504 | render_timeout |
O documento levou mais do que o seu plano permite. |
Rode POST /v1/validate com o mesmo corpo enquanto monta o template: ele lista tudo o que o
serviço não suportou por completo, sem devolver o PDF nem usar crédito.
Leia Gerar um PDF, Autenticação e Erros e limites.
Mais guias de C#
- Gerar PDF no ASP.NET Core: MVC, Razor Pages e minimal APIs
- Converter página web em PDF em C# sem navegador headless
- Gerador de relatório PDF em C#: tabela paginada com totais
- Salvar PDF em C#: em disco, como download ou em blob storage
- HTML para PDF em C#: PdfSharp, QuestPDF, iText, Puppeteer ou API
- Gerar PDF no Blazor: Server e WebAssembly
- Gerar PDF no Azure Functions sem empacotar um navegador
- Gerar milhares de PDFs em C#: ritmo, 429 e novas tentativas seguras
Continue lendo
Código e integrações
Gerar PDF no ASP.NET Core: MVC, Razor Pages e minimal APIs
Transforme uma view Razor em PDF no ASP.NET Core com uma chamada de API: renderizador de views, view pronta para impressão, action MVC e handler do Razor Pages.
3 min de leitura
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