Oltre il try-catch: Result Pattern e resilienza con Polly in C#
Scritto da Marco Morello il 15 novembre 2026
💡 In sintesi: lanciare eccezioni per gestire errori prevedibili o avvolgere tutto in un
try-catchgenerico equivale a coprire la spia dell'olio con un pezzo di nastro isolante nero. In questa guida vediamo come rendere espliciti i fallimenti di dominio con il Result Pattern in C# e come proteggere le chiamate esterne da timeout e guasti a cascata con Microsoft.Extensions.Http.Resilience (Polly v8).
1. La spia dell'olio coperta col nastro isolante
Dopo più di 230.000 chilometri in sella a una moto, impari presto una verità scomoda: l'affidabilità assoluta non esiste. Prima o poi un cablaggio si ossida, un sensore dell'ABS sporco manda una lettura fuori scala o una pompa della benzina inizia a perdere pressione sotto sforzo.
La differenza tra restare piantati in mezzo a un passo di montagna e riuscire a rientrare a valle sta tutta in come è stata progettata la centralina. Se un parametro esce dai margini previsti, l'elettronica non taglia l'accensione lasciandoti senza trazione in curva: isola il componente difettoso, entra in modalità recovery, accende una spia chiara sul cruscotto e ti permette di proseguire in sicurezza.
Nel codice C# che incontro tutti i giorni, troppo spesso facciamo l'esatto opposto. Da una parte
lanciamo eccezioni per qualunque regola di business violata — un cliente non trovato, un preventivo
scaduto, un codice ricambio inesistente. Dall'altra avvolgiamo interi blocchi di applicazione in un
try { ... } catch (Exception ex) generico, logghiamo un messaggio vago e restituiamo
null o un errore HTTP 500 indistinto.
In officina, quel comportamento ha un nome preciso: mettere un pezzo di nastro isolante nero sopra la spia dell'olio. Non hai risolto il problema; ti sei solo tolto la possibilità di capire cosa sta succedendo prima che il motore grippi.
2. Il vero costo delle eccezioni (non è solo questione di CPU)
In .NET, lanciare un'eccezione non è un'operazione gratuita. Quando il runtime esegue throw,
deve congelare il flusso corrente, risalire lo stack delle chiamate (stack unwinding),
allocare memoria sull'heap e costruire lo stack trace completo. Se succede una volta ogni
tanto per un guasto grave, il costo è trascurabile. Se succede migliaia di volte al minuto perché usi
NotFoundException per gestire una ricerca senza risultati, stai bruciando risorse.
Ma il danno peggiore non è nelle prestazioni. È nell'onestà dell'architettura. Guarda questa firma:
public Task<QuoteDto> GenerateQuoteAsync(QuoteRequest request, CancellationToken ct);
Cosa ti dice questo metodo? Ti promette che, dandogli una QuoteRequest, ti restituirà un
QuoteDto. Non ti dice che potrebbe fallire se la partita IVA non è valida, se il listino
prezzi è scaduto o se il server del fornitore non risponde. Per saperlo devi aprire l'implementazione,
leggerti tutte le dipendenze a cascata e sperare di aver intercettato ogni possibile throw
nascosto nei bassifondi del codice. Una firma così mente al chiamante.
La regola di confine tra Dominio e Bug
- Fallimenti prevedibili (Dominio e Integrazione): input non validi,
stato non coerente, record mancante, API esterna irraggiungibile. Fanno parte del normale
funzionamento e vanno resi espliciti nella firma tramite
Result<T>. - Guasti catastrofici (Bug e Crash irreversibili):
NullReferenceExceptionper un errore di programmazione, disco pieno, memoria esaurita. Qui il sistema deve fermarsi e far scattare gli allarmi.
3. Il Result Pattern: contratti onesti senza dipendenze esterne
Per rendere espliciti i fallimenti prevedibili non serve installare subito librerie pesanti. Possiamo costruire un'implementazione pulita, immutabile e production-ready in meno di settanta righe di C#.
Partiamo dalla definizione dell'errore di dominio tramite un sealed record:
namespace Workshop.Core.Common;
public sealed record Error(string Code, string Message, ErrorType Type)
{
public static readonly Error None = new(string.Empty, string.Empty, ErrorType.None);
public static Error Validation(string code, string message) =>
new(code, message, ErrorType.Validation);
public static Error NotFound(string code, string message) =>
new(code, message, ErrorType.NotFound);
public static Error Conflict(string code, string message) =>
new(code, message, ErrorType.Conflict);
public static Error ExternalFailure(string code, string message) =>
new(code, message, ErrorType.ExternalFailure);
}
public enum ErrorType
{
None = 0,
Validation = 1,
NotFound = 2,
Conflict = 3,
ExternalFailure = 4
}
Ora costruiamo il contenitore Result<T>. Nota una scelta architetturale precisa:
invece di usare uno struct, usiamo una sealed class con costruttore
private. In C#, qualsiasi struct possiede un costruttore implicito senza
parametri (default(Result<T>)) che lascerebbe IsSuccess a
false e Error a null, violando l'invariante dell'oggetto. Con una
classe sigillata e factory method statici, garantiamo che un Result<T> possa nascere
solo in due stati validi: successo con valore oppure fallimento con errore valorizzato.
namespace Workshop.Core.Common;
public sealed class Result<T>
{
private readonly T? _value;
private Result(T value)
{
IsSuccess = true;
_value = value;
Error = Error.None;
}
private Result(Error error)
{
if (error == Error.None)
throw new ArgumentException("Un risultato fallito deve contenere un errore valido.", nameof(error));
IsSuccess = false;
_value = default;
Error = error;
}
public bool IsSuccess { get; }
public bool IsFailure => !IsSuccess;
public Error Error { get; }
public T Value => IsSuccess
? _value!
: throw new InvalidOperationException($"Impossibile accedere a Value su un risultato fallito: {Error.Code}");
public static Result<T> Success(T value) => new(value);
public static Result<T> Failure(Error error) => new(error);
public TResult Match<TResult>(
Func<T, TResult> onSuccess,
Func<Error, TResult> onFailure) =>
IsSuccess ? onSuccess(_value!) : onFailure(Error);
public static implicit operator Result<T>(T value) => Success(value);
public static implicit operator Result<T>(Error error) => Failure(error);
}
Gli operatori impliciti (implicit operator) rendono l'uso quotidiano scorrevole quanto un
ritorno normale, ma con tutta la sicurezza del compilatore. Usa il selettore qui sotto per confrontare
come cambia un endpoint ASP.NET Core Minimal API:
L'endpoint deve indovinare quali eccezioni potrebbero esplodere nei livelli sottostanti. Il
catch (Exception) finale nasconde qualsiasi anomalia imprevista.
app.MapPost("/api/quotes", async (QuoteRequest request, IQuoteService service, CancellationToken ct) =>
{
try
{
var quote = await service.GenerateQuoteAsync(request, ct);
return Results.Ok(quote);
}
catch (ValidationException ex)
{
return Results.BadRequest(new { error = ex.Message });
}
catch (SupplierUnavailableException)
{
return Results.StatusCode(StatusCodes.Status503ServiceUnavailable);
}
catch (Exception)
{
// Il classico nastro isolante nero sulla spia
return Results.Problem("Errore generico");
}
});
Nessun try-catch nell'endpoint: la firma restituisce
Result<QuoteDto> e Match traduce in modo deterministico in
TypedResults.
app.MapPost("/api/quotes", async (
QuoteRequest request,
IQuoteService service,
CancellationToken ct) =>
{
Result<QuoteDto> result = await service.GenerateQuoteAsync(request, ct);
return result.Match<IResult>(
onSuccess: quote => TypedResults.Ok(quote),
onFailure: error => error.ToProblemDetails());
})
.Produces<QuoteDto>(StatusCodes.Status200OK)
.ProducesProblem(StatusCodes.Status400BadRequest)
.ProducesProblem(StatusCodes.Status503ServiceUnavailable);
Dove l'extension method ToProblemDetails() centralizza una volta per tutte la traduzione
tra gli errori di dominio e gli status code HTTP standard:
public static class ErrorHttpExtensions
{
public static IResult ToProblemDetails(this Error error)
{
var statusCode = error.Type switch
{
ErrorType.Validation => StatusCodes.Status400BadRequest,
ErrorType.NotFound => StatusCodes.Status404NotFound,
ErrorType.Conflict => StatusCodes.Status409Conflict,
ErrorType.ExternalFailure => StatusCodes.Status503ServiceUnavailable,
_ => StatusCodes.Status500InternalServerError
};
return TypedResults.Problem(
title: error.Code,
detail: error.Message,
statusCode: statusCode);
}
}
4. Quando il problema è fuori dalla tua officina: Polly e Http.Resilience
Finché resti dentro i confini del tuo dominio, Result<T> ti dà il controllo totale.
Ma appena il tuo backend attraversa la rete per interrogare un servizio esterno — l'API di un fornitore
ricambi, un gateway di pagamento, un modello AI o un bridge verso un PLC — entri in territorio ostile.
La rete non è affidabile. I pacchetti si perdono, i DNS rallentano, i server remoti vanno in
sovraccarico. Se lasci un HttpClient nudo a fare chiamate senza protezioni, basta che un
servizio esterno impieghi 30 secondi a rispondere per esaurire i thread disponibili e tirare giù tutto
il tuo backend per effetto domino.
In .NET moderno, la risposta standard si chiama
Microsoft.Extensions.Http.Resilience,
costruita sopra Polly v8 e integrata nativamente nella Dependency Injection. Una
pipeline di resilienza ben tarata applica quattro difese in sequenza precisa:
Il tempo massimo assoluto che il chiamante è disposto ad aspettare, inclusi tutti gli eventuali tentativi di retry. Evita che una richiesta resti appesa all'infinito.
In caso di singhiozzo temporaneo (es. HTTP 503), riprova aumentando l'attesa (200ms → 400ms → 800ms) con un ritardo casuale (jitter) per evitare l'effetto valanga sul server remoto.
Il magnetotermico del quadro elettrico: dopo N fallimenti consecutivi apre il circuito (OPEN) bloccando le chiamate in 1 ms (fail-fast). Dopo il cooldown testa la linea con una sonda (HALF-OPEN).
Il limite di tempo concesso a ogni singolo tentativo individuale dentro il ciclo di retry, così un tentativo bloccato viene interrotto subito per lasciare spazio al successivo.
5. Banco Prova: metti sotto stress la linea
Prima di vedere il cablaggio in C#, verifica con i tuoi occhi cosa succede ai tempi di risposta e alla stabilità quando un servizio esterno inizia a perdere colpi. Abbassa l'affidabilità al 25%, lancia una raffica di 5 richieste con Polly + Result<T> attivi e poi ripeti il test disattivando la protezione.
Simulatore Circuit Breaker & Result<T>
Regola l'affidabilità del servizio esterno, lancia una raffica di richieste e osserva la differenza
tra un approccio try-catch tradizionale e una pipeline protetta da
Polly + Result Pattern.
// In attesa di una chiamata... Result<QuoteDto> result = await _service.GetQuoteAsync();
6. Cablaggio reale in Program.cs e confine infrastrutturale
Portiamo ora questo comportamento dentro un'applicazione .NET reale. Installiamo il pacchetto ufficiale Microsoft:
dotnet add package Microsoft.Extensions.Http.Resilience
In Program.cs, registriamo il client tipizzato agganciando
AddStandardResilienceHandler(). Questo singolo metodo configura l'intera catena secondo le
linee guida ufficiali, permettendoci di tarare le soglie sul nostro caso d'uso:
using Microsoft.Extensions.Http.Resilience;
using Polly;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient<ISupplierPriceClient, SupplierPriceClient>(client =>
{
client.BaseAddress = new Uri(builder.Configuration["SupplierApi:BaseUrl"]!);
client.Timeout = Timeout.InfiniteTimeSpan; // Delegato alla pipeline Polly
})
.AddStandardResilienceHandler(options =>
{
// 1. Timeout massimo complessivo della richiesta (inclusi retry)
options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(10);
// 2. Retry con Exponential Backoff + Jitter
options.Retry.MaxRetryAttempts = 2;
options.Retry.Delay = TimeSpan.FromMilliseconds(300);
options.Retry.BackoffType = DelayBackoffType.Exponential;
options.Retry.UseJitter = true;
// 3. Circuit Breaker: scatta se almeno il 50% delle chiamate fallisce su minimo 5 richieste
options.CircuitBreaker.FailureRatio = 0.5;
options.CircuitBreaker.MinimumThroughput = 5;
options.CircuitBreaker.SamplingDuration = TimeSpan.FromSeconds(15);
options.CircuitBreaker.BreakDuration = TimeSpan.FromSeconds(20);
// 4. Timeout del singolo tentativo
options.AttemptTimeout.Timeout = TimeSpan.FromSeconds(3);
});
Tradurre le eccezioni Polly sul confine infrastrutturale
C'è un dettaglio che molti dimenticano quando introducono Polly: Polly lavora comunque con le
eccezioni. Quando il circuito è aperto o tutti i retry falliscono, la pipeline lancia
BrokenCircuitException o TimeoutRejectedException.
Se lasci uscire queste eccezioni dal client HTTP, hai inquinato il tuo dominio con dettagli
infrastrutturali. Il posto giusto per catturarle è esattamente sul confine del layer
Infrastructure, traducendole in un Result<T> pulito prima che
risalgano verso l'Application layer:
using System.Net.Http.Json;
using Polly.CircuitBreaker;
using Polly.Timeout;
using Workshop.Core.Common;
namespace Workshop.Infrastructure.Suppliers;
public sealed class SupplierPriceClient(
HttpClient httpClient,
ILogger<SupplierPriceClient> logger) : ISupplierPriceClient
{
public async Task<Result<decimal>> GetPartPriceAsync(string partCode, CancellationToken ct)
{
try
{
using var response = await httpClient.GetAsync($"/api/parts/{Uri.EscapeDataString(partCode)}", ct);
if (response.StatusCode == System.Net.HttpStatusCode.NotFound)
{
return Error.NotFound("PART_NOT_FOUND", $"Ricambio '{partCode}' non presente a listino.");
}
if (!response.IsSuccessStatusCode)
{
return Error.ExternalFailure("SUPPLIER_HTTP_ERROR", $"Il fornitore ha risposto con {(int)response.StatusCode}.");
}
var payload = await response.Content.ReadFromJsonAsync<PartPriceResponse>(ct);
return payload is not null
? Result<decimal>.Success(payload.UnitPrice)
: Error.ExternalFailure("SUPPLIER_INVALID_PAYLOAD", "Risposta del fornitore vuota o malformata.");
}
catch (BrokenCircuitException ex)
{
logger.LogWarning(ex, "Circuit breaker aperto verso l'API fornitore per il codice {PartCode}", partCode);
return Error.ExternalFailure("SUPPLIER_CIRCUIT_OPEN", "Listino fornitore temporaneamente isolato per instabilità.");
}
catch (TimeoutRejectedException ex)
{
logger.LogWarning(ex, "Timeout superato verso l'API fornitore per il codice {PartCode}", partCode);
return Error.ExternalFailure("SUPPLIER_TIMEOUT", "Il server del fornitore non ha risposto nei tempi previsti.");
}
catch (HttpRequestException ex)
{
logger.LogError(ex, "Errore di rete verso l'API fornitore per il codice {PartCode}", partCode);
return Error.ExternalFailure("SUPPLIER_NETWORK_ERROR", "Impossibile contattare il server del fornitore.");
}
}
private sealed record PartPriceResponse(string Code, decimal UnitPrice);
}
catch (Exception) pigliatutto: se si verifica un bug imprevisto nel
codice o viene annullato il CancellationToken dell'utente
(OperationCanceledException), l'eccezione prosegue il suo corso naturale. Il resto
dell'applicazione non sa nemmeno che esista Polly: riceve un Result<decimal> e decide
serenamente se applicare un prezzo di fallback o avvisare l'operatore.
Collaudare il confine con xUnit
Come abbiamo visto nell'articolo dedicato al banco di collaudo con xUnit, un client costruito così si
testa in pochi millisecondi senza tirare su alcun server esterno, iniettando un
HttpMessageHandler stub:
[Fact]
public async Task GetPartPriceAsync_WhenSupplierReturns404_ReturnsNotFoundResult()
{
// Arrange
var handler = new StubHttpMessageHandler(_ => new HttpResponseMessage(System.Net.HttpStatusCode.NotFound));
var httpClient = new HttpClient(handler) { BaseAddress = new Uri("https://supplier.test") };
var sut = new SupplierPriceClient(httpClient, NullLogger<SupplierPriceClient>.Instance);
// Act
var result = await sut.GetPartPriceAsync("FLT-990", CancellationToken.None);
// Assert
Assert.True(result.IsFailure);
Assert.Equal(ErrorType.NotFound, result.Error.Type);
Assert.Equal("PART_NOT_FOUND", result.Error.Code);
}
7. Regole di ingaggio: quando fermarsi prima dell'over-engineering
In meccanica come nel software, usare una chiave dinamometrica calibrata al Newton-metro per stringere il tappo di plastica della vaschetta lavavetri non ti rende un professionista migliore: ti fa solo perdere tempo. Ecco una bussola rapida per decidere quale strumento tirare fuori dal carrello:
| Scenario | Strumento consigliato | Perché |
|---|---|---|
| Ricerca semplice dove "nessun risultato" è normale (es. filtro di ricerca) | T? o IReadOnlyList<T> vuota |
Non c'è alcun errore da descrivere: l'assenza è un dato valido. |
| Regola di business violata o stato non valido (es. preventivo già chiuso) | Result<T> |
Il chiamante deve sapere perché l'operazione non è passata e reagire di conseguenza. |
| Chiamate HTTP esterne, code messaggi, gateway AI, dispositivi di campo | Http.Resilience (Polly) + Result<T>
|
La rete è inaffidabile per natura: servono timeout, retry con jitter e circuit breaker. |
| Query locale su database in-process (es. SQLite) | Nessun Circuit Breaker | Se SQLite locale è giù, il processo stesso è compromesso: inutile aprire un circuito. |
| Bug di programmazione o configurazione critica mancante all'avvio | Exception nativa |
Il sistema deve fermarsi subito e segnalare l'anomalia agli sviluppatori. |
Un sistema resiliente non è un sistema che non sbaglia mai. È un sistema che non mente sulle proprie vulnerabilità, isola i guasti prima che si propaghino e ti permette di continuare a viaggiare anche quando il meteo sul passo cambia all'improvviso.