Sviluppo Software
Marco Morello
15 novembre 2026
10 min read
Centralina diagnostica e resilienza software in C# con Result Pattern e Polly
Quando un sensore va fuori tolleranza, la centralina non spegne il motore: isola il guasto e ti porta a casa.

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-catch generico 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): NullReferenceException per 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:

Confronto Endpoint 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

Flusso architetturale Polly v8 e Result Pattern in C# Schema del passaggio dalla chiamata applicativa attraverso la pipeline Polly (Timeout, Retry con Jitter, Circuit Breaker) fino al confine infrastrutturale che restituisce Result.Success o Result.Failure. ARCHITETTURA RESILIENTE // POLLY v8 + RESULT<T> ZERO ECCEZIONI NEL DOMINIO APPLICATION QuoteService Chiama il client senza try-catch Task<Result<T>> POLLY v8 RESILIENCE PIPELINE 1. Total Request Timeout (10s) 2. Retry + Exponential Backoff & Jitter 3. Circuit Breaker CLOSED → OPEN (Fail-Fast) → HALF-OPEN 4. Attempt Timeout (3s) → API Esterna Confine Infrastructure (traduce BrokenCircuit / Timeout in Result<T>) Result<T>.Success(value) Dati validati pronti per il dominio Minimal API → 200 OK Result<T>.Failure(error) ErrorType: ExternalFailure / NotFound Minimal API → RFC 7807 ProblemDetails
Il confine infrastrutturale assorbe le eccezioni di Polly e instrada il flusso su due binari espliciti verso l'Application layer.

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:

1 Total Request Timeout

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.

2 Retry + Exponential Backoff & Jitter

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.

3 Circuit Breaker (Closed / Open / Half-Open)

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).

4 Attempt Timeout

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.

BANCO PROVA // DIAGNOSTICA DI RETE

Simulatore Circuit Breaker & Result<T>

CIRCUITO: CLOSED (OPERATIVO)

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.

65%
0% (Down) 50% (Instabile) 100% (Stabile)
Result.Success 0
Result.Failure (Gestiti) 0
Timeout / Crash 0
Latenza Media 0 ms
Contratto restituito al chiamante (C#)
// In attesa di una chiamata...
Result<QuoteDto> result = await _service.GetQuoteAsync();
Log Telemetria Linea
[INIT] Banco prova pronto. Soglia Circuit Breaker: 3 fallimenti consecutivi.

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);
}
Nota che non c'è nessun 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.

Prossimamente...

Apriremo il cofano di PreventivoAi, il micro-SaaS in .NET a cui sto lavorando per trasformare messaggi e vocali d'officina in preventivi PDF pronti da inviare: vedremo come organizzarlo con la Vertical Slice Architecture, tra meno cartelle vuote, più coesione per funzionalità e zero over-engineering.

← Torna indietro