Generar miles de PDF en C#: ritmo, 429 y reintentos seguros
Publicado el 3 min de lectura
Facturas de fin de mes, un certificado para cada asistente, un extracto para cada cliente: tarde o
temprano necesitas miles de PDF, no uno. El código obvio, una lista de tareas y Task.WhenAll,
envía todas las peticiones a la vez, y el servicio responde 429 a la mayoría. Esta guía arma un
ejecutor de lotes que respeta la tasa de tu plan, repite lo que es seguro repetir y se puede
parar y reanudar sin rehacer el mismo trabajo. Usa el estilo de cliente tipado de la
guía de C# y ASP.NET Core.
Conoce primero los límites
- La tasa de peticiones pertenece a la cuenta. Tu plan fija cuántas peticiones por minuto puede hacer la cuenta, y todas las claves la comparten. Una segunda clave no sube el límite; solo reparte la misma cuota. Los números están en la página de planes.
- Un renderizado cuesta un crédito, y uno que falla no cuesta nada. Se toma un crédito cuando empieza el renderizado y se devuelve si falla, así que repetir un fallo es seguro.
- Sin créditos llega un
402. No se renderizó nada, y cualquier otra petición fallaría igual, así que el lote entero debe parar.
Comprueba el saldo antes de empezar. GET /v1/me devuelve tu plan y tus créditos:
public sealed record Me(string Plan, long Credits);
var me = await http.GetFromJsonAsync<Me>("v1/me", cancellationToken);if (me!.Credits < jobs.Count) throw new InvalidOperationException($"{me.Credits} créditos para {jobs.Count} documentos.");Controla el ritmo de las llamadas
Un token bucket deja pasar una petición cada cierto tiempo, sea cual sea el número de workers.
.NET trae uno en System.Threading.RateLimiting:
using System.Threading.RateLimiting;
var limiter = new TokenBucketRateLimiter(new TokenBucketRateLimiterOptions{ TokenLimit = 1, TokensPerPeriod = 1, ReplenishmentPeriod = TimeSpan.FromSeconds(60.0 / requestsPerMinute), QueueLimit = int.MaxValue, QueueProcessingOrder = QueueProcessingOrder.OldestFirst, AutoReplenishment = true,});Fija requestsPerMinute algo por debajo de la tasa de tu plan, para que otras llamadas de la misma
cuenta sigan cabiendo. Cada worker toma un token antes de enviar una petición.
El ejecutor
using System.Collections.Concurrent;using System.Net;using System.Net.Http.Json;
public sealed record Job(string Number, string TemplateId, string Locale, Dictionary<string, object?> Data);
public sealed class OutOfCreditsException : Exception;
public sealed class BatchRenderer(HttpClient http, TokenBucketRateLimiter limiter, int workers){ public async Task<IReadOnlyList<string>> RunAsync( IEnumerable<Job> jobs, string folder, CancellationToken cancellationToken) { var failed = new ConcurrentBag<string>(); var options = new ParallelOptions { MaxDegreeOfParallelism = workers, CancellationToken = cancellationToken, };
await Parallel.ForEachAsync(jobs, options, async (job, token) => { var path = Path.Combine(folder, $"{job.Number}.pdf"); if (File.Exists(path)) return; // hecho en una ejecución anterior
try { var pdf = await RenderAsync(job, token); await File.WriteAllBytesAsync(path + ".part", pdf, token); File.Move(path + ".part", path, overwrite: true); } catch (OutOfCreditsException) { throw; } // para el lote entero catch (Exception) when (!token.IsCancellationRequested) { failed.Add(job.Number); // un documento malo no frena a los demás } });
return failed.ToArray(); }}Tres hábitos hay en ese código:
- Escribe en un nombre temporal y luego muévelo. Una ejecución interrumpida a medias nunca deja medio archivo con aspecto de terminado.
- Salta lo que ya existe. Lanza el mismo lote otra vez y solo hace los documentos que faltan, así que reanudar una ejecución parada no cuesta nada.
- Guarda los fallos. El método devuelve los números que fallaron, para que los revises, corrijas los datos y ejecutes de nuevo.
Repite solo lo seguro
Este método pertenece a la clase BatchRenderer:
private async Task<byte[]> RenderAsync(Job job, CancellationToken cancellationToken){ for (var attempt = 1; ; attempt++) { using var lease = await limiter.AcquireAsync(1, cancellationToken); using var response = await http.PostAsJsonAsync( "v1/render", new { template_id = job.TemplateId, data = job.Data, locale = job.Locale }, cancellationToken);
if (response.IsSuccessStatusCode) return await response.Content.ReadAsByteArrayAsync(cancellationToken);
if (response.StatusCode == HttpStatusCode.PaymentRequired) throw new OutOfCreditsException();
var retry = response.StatusCode is HttpStatusCode.TooManyRequests or HttpStatusCode.ServiceUnavailable || (int)response.StatusCode >= 500; if (!retry || attempt == 5) throw new InvalidOperationException($"{job.Number}: {(int)response.StatusCode}");
var wait = response.Headers.RetryAfter?.Delta ?? TimeSpan.FromSeconds(Math.Pow(2, attempt)); await Task.Delay(wait + TimeSpan.FromMilliseconds(Random.Shared.Next(0, 500)), cancellationToken); }}| Estado | Qué hace el ejecutor |
|---|---|
| 200 | Devuelve el PDF. |
| 402 | Para el lote entero: sin créditos, no se renderizó nada. |
| 429, 503, 5xx | Espera el Retry-After, o retrocede, y lo intenta de nuevo, hasta cinco veces. Un renderizado que falla no consume crédito. |
| Otros 4xx | No repite. La petición es incorrecta; el documento se registra como fallo. |
A cada espera se le suma un pequeño retraso aleatorio, para que los workers que se frenaron juntos no vuelvan en el mismo instante.
Un caso que evitar
Si el servicio termina un renderizado pero tu lado nunca recibe la respuesta, por ejemplo por un
tiempo límite de red, y vuelves a enviar la petición, es un renderizado nuevo y cuesta otro
crédito. Mantén el tiempo límite del HttpClient por encima del límite de tiempo de tu plan, para
que un documento lento no se abandone demasiado pronto, y lee el X-Render-Id de cada respuesta
en tu registro, para distinguir los documentos que se hicieron de los que no.
Mantén cada petición pequeña
Envía una plantilla guardada y solo los datos, como en esta guía, y no todo el HTML cada vez. El
tamaño de una entrada lo limita tu plan; una petición demasiado grande responde 413. Consulta
Generar con una plantilla guardada.
Lee Errores y límites y Generar un PDF. Para una versión de la misma idea basada en colas, consulta Generar un PDF en Azure Functions.
Sigue leyendo
Código e integraciones
Generar un PDF en ASP.NET Core: MVC, Razor Pages y minimal APIs
Convierte una vista Razor en PDF en ASP.NET Core con una llamada a la API: renderizador de vistas, vista lista para imprimir, acción MVC y handler de Razor Pages.
3 min de lectura
Código e integraciones
Convertir una página web a PDF en C# sin navegador headless
Descarga una página con HttpClient y convierte su HTML en PDF con una llamada a la API en C#. Qué páginas admite, cuáles no y cómo comprobarlo de antemano.
3 min de lectura
Código e integraciones
Generador de informes PDF en C#: tabla paginada con totales
Crea un informe PDF en C# a partir de una lista de objetos: tabla con la cabecera repetida en cada página, total, números de página y recuento de páginas.
3 min de lectura
Código e integraciones
Guardar un PDF en C#: en disco, como descarga o en blob storage
Guarda el PDF que devuelve una llamada de renderizado en C#: escríbelo en disco, envíalo como descarga en ASP.NET Core, usa un enlace firmado o súbelo al storage.
2 min de lectura