ASP.NET Core background jobs: RabbitMQ, IHostedService e idempotency Architettura e trade-off reali per code asincrone in .NET: IHostedService vs BackgroundService, quorum queues, back-pressure e atomicità tra database e broker

Quando un endpoint HTTP deve innescare operazioni lente, costose o fragili, tenerle dentro la request quasi sempre non è la scelta ottimale: la latenza percepita aumenta, l'eventuale errore diventa molto più difficile da gestire, ma soprattutto il completamento del lavoro diventa indissolubilmente legato alla vita della connessione client - la quale, come si sa, è tutto fuorché garantita, specie in scenari di mobile device e/o connessioni wireless. In ASP.NET Core, il salto di qualità arriva quando si separa l’ingresso della richiesta dall’esecuzione vera e propria del job, delegando quest’ultima a un processo worker dedicato.

La combinazione più classica, e ancora oggi una delle più solide, è questa: l’applicazione web valida la richiesta, persiste lo stato minimo necessario e pubblica un messaggio su un message-broker middleware come RabbitMQ; un worker .NET in background legge dalla coda, esegue il lavoro, aggiorna il database e gestisce retry, errori e telemetria. È un modello semplice da capire, ma va implementato con un po’ di disciplina: idempotenza, controllo del flusso, shutdown pulito, distinzione tra errori transitori e permanenti, e soprattutto una strategia credibile per l’atomicità tra database e broker.

Perché spostare il lavoro "fuori" conviene

I casi d’uso sono noti: elaborazione documenti, invio email, generazione report, sincronizzazioni verso sistemi esterni, indexing, import massive, chiamate a provider lenti o instabili. In tutti questi scenari, la request HTTP dovrebbe limitarsi a fare il minimo indispensabile: validare, scrivere i dati iniziali e accodare il lavoro.

Il vantaggio non è soltanto la riduzione della latenza lato utente. Separare producer e consumer consente di ritentare i job in modo indipendente dalla sessione HTTP originaria, di scalare i worker orizzontalmente senza toccare la Web API e di contenere meglio i fallimenti parziali. È il pattern di base che sta dietro a gran parte dei sistemi che devono restare reattivi anche quando il lavoro reale è lento o intermittente. Il materiale che mi hai allegato va esattamente in questa direzione, pur essendo legato a un progetto specifico; qui lo rendo volutamente più generale. :contentReference[oaicite:0]{index=0}

Architettura di base

Una baseline sensata, senza complicarla troppo, di solito è composta da questi elementi:

• una Web API ASP.NET Core che riceve la richiesta e pubblica un job;
• un’astrazione interna, ad esempio IJobQueue, per non spargere nel codice dipendenze dirette dal client RabbitMQ;
• un’implementazione concreta del producer che serializza il payload e lo invia a exchange e queue;
• un worker separato, basato su Generic Host, che consuma i messaggi;
• una tabella applicativa per tracciare lo stato del job, gli errori e il numero di tentativi;
• telemetria sui risultati: completato, fallito, scartato, ritentato.

Il ciclo di vita tipico è lineare: il producer scrive i metadati nel database, pubblica un messaggio con l’identificativo del lavoro, il consumer lo riceve, porta il job in stato Processing, esegue l’operazione e poi lo marca come Completed o Failed. Se il messaggio viene rideliverato, entrano in gioco idempotenza e retry policy. Il file allegato descrive proprio questa impostazione, con una persistenza esplicita delle transizioni di stato per evitare di dipendere dal broker come unica fonte di verità. :contentReference[oaicite:1]{index=1}

HTTP Producer: quando (e come) pubblicare

Qui c’è un primo equivoco frequente: "rispondere subito" non significa pubblicare alla cieca e basta. La request dovrebbe uscire solo dopo aver salvato nel database ciò che serve per ricostruire il job, verificarne la validità e, idealmente, garantire che il messaggio verrà pubblicato davvero. Questo ultimo punto è quello che separa le demo dai sistemi che reggono in produzione.

Un esempio semplificato può essere questo:

Funziona, ma ha un problema: tra SaveChangesAsync e EnqueueAsync esiste una finestra in cui il database può essere aggiornato correttamente ma il messaggio non arrivare mai al broker. È qui che l’outbox pattern smette di essere un vezzo architetturale e diventa una necessità.

Outbox pattern: atomicità tra database e broker

Il problema è semplice: non esiste una transazione distribuita affidabile e conveniente, nella maggior parte degli scenari moderni, tra il tuo database applicativo e RabbitMQ. Se aggiorni il DB e poi pubblichi, puoi perdere il messaggio; se pubblichi e poi fallisce il commit, puoi avere un evento che descrive qualcosa che in realtà non è mai stato salvato.

Il transactional outbox risolve questo punto memorizzando il messaggio in una tabella outbox dentro la stessa transazione che salva i dati applicativi; un processo separato, o un publisher dedicato, legge poi l’outbox e inoltra i messaggi al broker. In questo modo l’aggiornamento del database e la registrazione dell’evento sono atomici dal punto di vista locale. È esattamente il problema che il pattern nasce per risolvere. :contentReference[oaicite:2]{index=2}

In pratica, il flusso diventa questo:

1. salvi entità business e record outbox nella stessa transazione;
2. committi una volta sola;
3. un publisher in background legge i record outbox non inviati;
4. pubblica su RabbitMQ;
5. marca il record outbox come inviato.

Non elimina la necessità di idempotenza lato consumer, perché anche il publisher può ritentare o inviare due volte in certi edge case, ma elimina il punto più pericoloso: il disallineamento silenzioso tra stato del database e stato del broker.

Consumer in .NET: IHostedService o BackgroundService?

In ASP.NET Core e più in generale nel Generic Host, un servizio in background implementa IHostedService. BackgroundService non è un’alternativa concettuale: è una classe base fornita dal framework che implementa IHostedService e ti lascia concentrare la logica lunga dentro ExecuteAsync. La documentazione Microsoft lo descrive in modo esplicito: BackgroundService è una base class per implementare servizi a lunga esecuzione, mentre IHostedService resta il contratto fondamentale. :contentReference[oaicite:3]{index=3}

La regola pratica, nella maggior parte dei casi, è molto semplice:

• usa BackgroundService quando hai un loop di consumo continuo, un poller o un worker che vive per tutta la durata del processo;
• implementa direttamente IHostedService quando ti serve controllo più fine su start, stop, timer, risorse unmanaged o più fasi di inizializzazione e teardown. Microsoft lo segnala chiaramente come scelta utile quando BackgroundService non basta. :contentReference[oaicite:4]{index=4}

Per un consumer RabbitMQ classico, BackgroundService è quasi sempre la scelta più naturale:

Back-pressure reale: importanza del prefetchCount

Chi lavora con RabbitMQ prima o poi ci sbatte contro: se lasci troppa libertà al broker, il consumer può ritrovarsi sommerso di messaggi non ancora ackati, con memoria in crescita, latenza che peggiora e comportamento poco prevedibile. Il parametro chiave, in questo caso, è il prefetchCount, cioè il limite ai messaggi non ackati che un consumer può avere in carico.

RabbitMQ documenta il prefetch proprio come meccanismo per limitare il numero di delivery non confermate; inoltre segnala che prefetch troppo alto porta a più messaggi unacked e a maggiore uso di memoria sul broker. Nelle quorum queues il tema è ancora più importante, e la documentazione osserva che i consumer beneficiano di valori di prefetch adeguati per non restare “affamati”, ma questo non significa spararlo a caso verso l’alto. :contentReference[oaicite:5]{index=5}

La regola empirica, qui, è semplice:

• se il job è pesante, parti con un prefetchCount basso, ad esempio 4, 8 o 16;
• se il job è rapido e I/O-bound, puoi salire, ma misurando davvero throughput, RAM e tempi di ack;
• evita autoAck nei consumer che fanno lavoro reale: il back-pressure con ack manuali è una delle protezioni più utili che RabbitMQ mette a disposizione. :contentReference[oaicite:6]{index=6}

In altre parole, prefetchCount non è un dettaglio da tuning finale: è una parte del contratto operativo tra broker e worker.

Idempotency e gestione dei duplicati

Con RabbitMQ, come con quasi tutti i broker tradizionali, devi ragionare in termini di at-least-once delivery. Se il consumer crasha dopo aver iniziato il lavoro ma prima dell’ack, il messaggio può essere rideliverato. Se il publisher ritenta, puoi vedere lo stesso payload due volte. Se hai un dead-letter loop configurato male, puoi persino moltiplicare il problema.

Per questo l’idempotenza non andrebbe trattata come un accessorio. Va progettata. Il file che mi hai passato lo dice in modo molto chiaro: la chiave non deve essere il delivery tag del broker, ma il payload logico del job, così da coprire anche i retry lato publisher. :contentReference[oaicite:7]{index=7}

Ci sono almeno tre strategie pragmatiche:

• vincolo univoco nel database su una chiave logica del job, ad esempio DocumentId + JobType;
• tabella o cache distribuita che registra i job in corso o già completati, con TTL ragionevole;
• handler progettati in modo da poter essere eseguiti più volte senza effetti collaterali duplicati.

Un esempio minimale, semplificato, può essere questo:

La forma concreta può cambiare, ma il principio resta quello: un messaggio rideliverato non deve raddoppiare gli effetti business.

Retry, dead-letter e stato applicativo del job

Un altro punto utile del materiale allegato è la scelta di persistere lo stato del job dentro il dominio applicativo, invece di affidarsi solo alla queue. È una scelta che condivido: il broker sa consegnare messaggi, non raccontare bene lo stato funzionale del processo. Se vuoi mostrare in UI che un job è in Processing, Completed, Failed o Skipped, serve quasi sempre una tabella applicativa dedicata. :contentReference[oaicite:8]{index=8}

In più, distinguere gli esiti aiuta anche sul piano operativo:

• Completed: il lavoro è finito correttamente;
• Failed: il tentativo è fallito e richiede retry o analisi;
• Skipped: il messaggio è arrivato, ma il dominio ha stabilito che non andava eseguito;
• Dead-lettered: il broker ha smesso di ritentare e ha isolato il messaggio per ispezione manuale.

Questa separazione evita uno degli errori più comuni: usare il dead-letter exchange come unico sistema di audit.

RabbitMQ classic vs quorum queues

Per anni le classic queues sono state la scelta di default in moltissimi progetti. Oggi, però, quando il requisito è l’affidabilità e non soltanto il throughput puro in scenari semplici, le quorum queues meritano molta attenzione. RabbitMQ le documenta come code replicate e fault-tolerant basate su un algoritmo tipo Raft, con caratteristiche pensate per ambienti dove la disponibilità conta davvero; allo stesso tempo, la documentazione ricorda che sono più pesanti su I/O disco e che il throughput cala con messaggi più grandi. :contentReference[oaicite:9]{index=9}

Tradotto in pratica:

• usa classic queues quando hai requisiti modesti, topologie semplici o contesti di sviluppo/test in cui vuoi il setup più leggero possibile;
• preferisci quorum queues quando il queue loss non è accettabile, il cluster è reale e vuoi una semantica di replica più robusta;
• misura sempre con il tuo carico: quorum non significa automaticamente “meglio in assoluto”, ma “più adatto” in certi trade-off operativi. :contentReference[oaicite:10]{index=10}

Per background jobs critici, oggi tendo a considerare le quorum queues una scelta molto sensata, purché il team sappia che costano qualcosa in più in termini di risorse e tuning.

Confronto con Channel<T> in-process

Qui vale la pena essere molto chiari, perché la confusione è frequente: Channel<T> e RabbitMQ non risolvono esattamente lo stesso problema. I channel di .NET sono strutture di sincronizzazione in memoria per producer e consumer asincroni nello stesso processo; funzionano benissimo per code locali, pipeline interne e task sequenziali o bounded dentro una singola istanza applicativa. La documentazione Microsoft li presenta proprio così. :contentReference[oaicite:11]{index=11}

Quindi:

• Channel<T> è ottimo quando il lavoro può restare nello stesso processo, non ti serve persistenza cross-restart e vuoi evitare la complessità di un broker esterno;
• RabbitMQ entra in gioco quando ti servono durabilità, disaccoppiamento tra processi, scalabilità indipendente, retry broker-level e isolamento del carico tra WebApp e worker;
• Channel<T> è più semplice da mantenere e più veloce in-process, ma se il processo cade perdi la coda in memoria, salvo meccanismi aggiuntivi tuoi.

In molti sistemi reali convivono entrambe le cose: Channel<T> per lavoro locale e leggero, RabbitMQ per il lavoro che deve sopravvivere al processo e scalare fuori dalla Web API.

Graceful shutdown e cancellazione dei token

Lo shutdown pulito di un worker viene spesso sottovalutato, poi in produzione ci si ritrova con job interrotti a metà, messaggi rideliverati in modo caotico e chiusure poco prevedibili durante deploy o scale down. Nel Generic Host, il ciclo di vita dell’applicazione è gestito dal runtime, e puoi agganciarti agli eventi di stop tramite IHostApplicationLifetime; la documentazione Microsoft lo mostra anche negli esempi dedicati ai queue service. :contentReference[oaicite:12]{index=12}

Quello che conviene fare, in pratica, è:

• smettere di accettare nuovi messaggi non appena inizia lo shutdown;
• lasciare finire quelli già in lavorazione, entro un timeout ragionevole;
• ackare solo a lavoro concluso davvero;
• chiudere connessione e channel dopo il drain, non prima.

Un esempio semplificato di hook sul lifetime può essere questo:

Non è il codice a fare la magia, ovviamente; il punto è la disciplina operativa: evitare di tirare giù il processo mentre il consumer ha ancora lavoro in corso senza sapere come chiuderlo.

Esempio di architettura

Se dovessi riassumere una baseline affidabile per background work in ASP.NET Core con RabbitMQ, andrei in questa direzione:

• Web API che persiste lo stato iniziale e registra l’evento in outbox;
• publisher outbox che inoltra i messaggi al broker con conferme adeguate;
• worker separato basato su BackgroundService;
• ack manuali e prefetchCount calibrato per il carico reale;
• idempotenza lato consumer, non opzionale;
• stato del job persistito nel database applicativo;
• dead-letter queue per i fallimenti permanenti;
• shutdown pulito agganciato al lifetime dell’host;
• telemetria su tempi, esiti, retry e saturazione del consumer.

Non è l’unica architettura possibile, ma è una di quelle che reggono meglio il passaggio dalla demo al sistema vero.

Conclusioni

Background work in ASP.NET Core non significa soltanto “spostare roba fuori dalla request”. Significa scegliere dove mettere il confine tra sincrono e asincrono, decidere quanto vuoi delegare a un broker esterno, gestire correttamente duplicati e retry, e costruire un consumer che sappia fermarsi bene oltre che partire bene.

RabbitMQ, in questo contesto, resta un’opzione molto solida: ti dà un disaccoppiamento reale tra producer e worker, ti permette di scalare i consumer in modo indipendente e, se lo usi con ack manuali, prefetch ragionato, DLQ, idempotenza e outbox, ti porta su una strada molto più affidabile del classico “fire-and-forget” appeso a una request HTTP. Channel<T> resta utilissimo, ma per un’altra classe di problemi; BackgroundService è quasi sempre la scelta giusta per il loop di consumo, mentre IHostedService serve quando vuoi controllo più fine; quorum queues e graceful shutdown non sono dettagli avanzati da rimandare, sono pezzi del disegno iniziale.

Quando questi elementi sono messi insieme bene, il sistema diventa più veloce lato utente, più prevedibile lato operativo e molto meno fragile quando iniziano i guasti veri, che poi è il momento in cui l’architettura smette di essere una slide e comincia a contare davvero.

Riferimenti

• Background tasks with hosted services in ASP.NET Core
• System.Threading.Channels in .NET
• .NET Generic Host
• Implement the IHostedService interface
• RabbitMQ Consumer Prefetch
• RabbitMQ Quorum Queues
• Quorum Queues and Flow Control
• Transactional Outbox Pattern