rustedf.cloud
Menu

Gerador de relatório PDF em C#: tabela paginada com totais

Publicado em 3 min de leitura

Um relatório são linhas que não cabem em uma página. Ele precisa de uma tabela que leve o cabeçalho para a folha seguinte, de um total no fim e de um “Página 2 de 5” em cada página. Em C#, isso é mais um trabalho de layout do que de código, e fica mais fácil quando o layout é HTML e CSS que você já conhece. Este guia monta um com a API do rustedf.cloud e um cliente tipado como o do guia de C# e ASP.NET Core.

Os dados

Envie as linhas como uma lista e os valores como texto:

using System.Globalization;
public sealed record SaleRow(string Product, int Quantity, string Amount);
var rows = sales
.Select(s => new SaleRow(
s.Product,
s.Quantity,
s.Total.ToString("0.00", CultureInfo.InvariantCulture)))
.ToList();

Um valor escrito como "1234.50" é formatado para o leitor pelo filtro currency, e isso evita as surpresas do ponto flutuante. O System.Text.Json renomeia as propriedades de um record (Product vira product), então o template usa os nomes em minúsculas.

O template

As regras de página, a tabela e o laço são todos HTML e CSS:

<style>
@page {
size: A4;
margin: 20mm;
@bottom-right { content: "Página " counter(page) " de " counter(pages); }
}
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>
<h1>{{ title }}</h1>
<p>{{ generated | date(style="long") }}</p>
<table>
<thead>
<tr><th>Produto</th><th class="number">Qtd</th><th class="number">Valor</th></tr>
</thead>
<tbody>
{% for row in rows %}
<tr>
<td>{{ row.product }}</td>
<td class="number">{{ row.quantity | number }}</td>
<td class="number">{{ row.amount | currency(code="BRL") }}</td>
</tr>
{% endfor %}
</tbody>
</table>
<p><strong>Total {{ total | currency(code="BRL") }}</strong></p>

Três detalhes fazem o trabalho de um relatório:

  • @page define o papel e a margem, e a caixa de margem de baixo guarda o número da página. Você não conta páginas: o total é preenchido quando o documento inteiro já foi diagramado.
  • A linha de cabeçalho de uma tabela é repetida em cada página que a tabela ocupa, então os títulos das colunas acompanham os dados.
  • break-inside: avoid impede que uma linha seja dividida entre duas páginas.

Renderize e leia a contagem de páginas

Guarde o template em um arquivo ou em um recurso embutido e envie-o como html, junto com os dados:

public async Task<(byte[] Pdf, int Pages)> RenderReportAsync(
string html, object data, CancellationToken cancellationToken = default)
{
using var response = await http.PostAsJsonAsync(
"v1/render",
new { html, data, locale = "pt-BR", title = "Relatório de vendas" },
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})");
}
var pages = int.Parse(response.Headers.GetValues("X-Pages").First());
return (await response.Content.ReadAsByteArrayAsync(cancellationToken), pages);
}
var data = new
{
title = "Vendas de outubro",
generated = DateTime.UtcNow.ToString("yyyy-MM-dd"),
rows,
total = rows.Sum(r => decimal.Parse(r.Amount, CultureInfo.InvariantCulture))
.ToString("0.00", CultureInfo.InvariantCulture),
};
var (pdf, pages) = await client.RenderReportAsync(template, data);

O cabeçalho X-Pages informa quantas páginas o relatório tem, então você pode exibi-lo ou recusar um relatório longo demais sem abrir o arquivo.

O html é enviado de novo a cada requisição. Se o mesmo relatório é gerado com frequência, salve o template na sua conta e envie só os dados com template_id; veja Gerar com um template salvo.

Quando o relatório é longo

Um relatório que cresce esbarra nos limites do plano, e cada limite tem a sua resposta:

Status code O que aconteceu
413 payload_too_large A requisição ou os dados passaram de um limite de tamanho.
422 invalid_template O template falhou, ou o relatório tem mais páginas do que o seu plano permite.
504 render_timeout O relatório levou mais tempo do que o limite do seu plano.

Dois limites valem para data em qualquer plano: no máximo 200.000 valores e 32 níveis de profundidade. Some e agrupe no seu banco de dados e envie o resultado; um relatório de cem mil linhas costuma pedir um resumo e um link para o detalhe, não todas as linhas.

Confira o layout

Envie o mesmo corpo para POST /v1/validate enquanto monta o relatório. Ele devolve o que o serviço não conseguiu usar e o número de páginas, sem PDF e sem crédito. Nos seus testes, acrescente "strict": true para que um relatório que passe a usar algo não suportado falhe com 422 strict_mode_rejected em vez de perder isso em silêncio.

Leia HTML e CSS suportados, Idiomas e formatação e Erros e limites. Para as regras de página em detalhe, veja Número de página, cabeçalho e rodapé em PDF.

← Todos os posts