Diamo per scontato che il servizio esterno sia sempre disponibile, che la rete funzioni, che le risposte arrivino velocemente e che, una volta stabilita la comunicazione, tutto continui a funzionare nello stesso modo.

Prendiamo un caso molto semplice:

Normalmente Catalog API risponde in 100 ms e tutto funziona perfettamente.

Poi, per qualche secondo, Catalog API restituisce 503 Service Unavailable. Oppure impiega 8 secondi a rispondere, smette del tutto di rispondere o viene sommersa di richieste quando la nostra applicazione riceve dieci volte il traffico previsto.

Una dependency può diventare non disponibile, lenta oppure sovraccaricata. E il nostro sistema deve essere progettato sapendo che, prima o poi, succederà.

È qui che entra in gioco la resilienza.

Da fault handling a resilience

La prima soluzione che viene naturale è gestire l’errore.

try
{
    var response = await catalogClient.GetAsync("/products/42");
    response.EnsureSuccessStatusCode();
}
catch (HttpRequestException ex)
{
    // Handle error
}

Non c’è nulla di sbagliato, ma abbiamo semplicemente deciso cosa fare dopo che l’operazione è fallita.

Rendere resiliente un’applicazione significa fare un passo in più.

Dobbiamo iniziare a chiederci:

• Cosa succede se la chiamata fallisce?
• Cosa succede se il servizio è lento?
• Cosa succede se continua a fallire?
• Cosa succede se stiamo inviando troppe richieste?
• Cosa succede se il fallimento è solo temporaneo?

La resilienza consiste quindi nel progettare esplicitamente come l’applicazione deve comportarsi in presenza di failure, cercando dove possibile di recuperare e, soprattutto, evitando che il problema di una dependency si propaghi al resto del sistema.

Ed è qui che Microsoft.Extensions.Resilience viene in nostro soccorso.

Microsoft.Extensions.Resilience

Chi sviluppa applicazioni .NET resilienti da qualche anno probabilmente conosce già Polly, una delle librerie più diffuse nell’ecosistema .NET per implementare strategie come retry, circuit breaker e timeout.

Con .NET 8, Microsoft ha introdotto due nuovi package costruiti sopra Polly v8: Microsoft.Extensions.Resilience e Microsoft.Extensions.Http.Resilience, come spiega nell’articolo sulle novità di .NET 8.

Oggi abbiamo quindi:

• Microsoft.Extensions.Resilience, che fornisce i meccanismi generali per costruire e integrare resilience pipeline.
• Microsoft.Extensions.Http.Resilience, che aggiunge funzionalità specifiche per HttpClient.

Il precedente package Microsoft.Extensions.Http.Polly è invece deprecato e Microsoft raccomanda di utilizzare i nuovi package per le nuove applicazioni. La documentazione sulla resilienza in .NET raccoglie le indicazioni aggiornate.

Per chi arriva da Polly il modello concettuale rimane familiare, anche perché i nuovi package Microsoft sono costruiti proprio sopra Polly. Prima di vedere il codice, però, conviene capire quali problemi possiamo risolvere.

Una panoramica delle strategie

Una resilience pipeline è una sequenza di strategie che avvolge l’operazione che vogliamo eseguire.

Nel caso di una chiamata HTTP possiamo immaginarla così:

Questa è proprio la pipeline standard fornita da Microsoft.Extensions.Http.Resilience. Microsoft la compone, nell’ordine, con rate limiter, timeout complessivo, retry, circuit breaker e timeout del singolo tentativo.

Per ora ci basta capire a grandi linee il ruolo di ognuna.

Il rate limiter controlla quante operazioni possono essere eseguite contemporaneamente verso la dependency (di default 1000, senza coda). L’obiettivo è evitare di esercitare una pressione eccessiva sul servizio che stiamo chiamando.

Il total timeout definisce quanto tempo concediamo all’intera operazione, compresi eventuali tentativi successivi.

Il retry permette di eseguire nuovamente un’operazione quando il failure potrebbe essere transitorio.

Il circuit breaker interrompe temporaneamente le chiamate quando la percentuale di failure verso una dependency supera una soglia (di default il 10% delle richieste in una finestra di 30 secondi, con almeno 100 richieste).

L’attempt timeout limita invece il tempo concesso a ogni singolo tentativo.

E configurarli può essere sorprendentemente semplice. Dopo aver aggiunto il package:

dotnet add package Microsoft.Extensions.Http.Resilience

basta una riga:

services
    .AddHttpClient("catalog", client =>
    {
        client.BaseAddress = new Uri("https://catalog.example.com");
    })
    .AddStandardResilienceHandler();

AddStandardResilienceHandler() associa al nostro HttpClient proprio la pipeline standard appena vista.

Questo non significa, però, che sia sufficiente aggiungere quella riga per rendere magicamente resiliente qualsiasi applicazione.

Non sempre riprovare è una buona idea

Prendiamo il retry.

Se ricevessimo 503 Service Unavailable, il problema potrebbe essere temporaneo e ritentare l’operazione può avere perfettamente senso.

Ma se invece ricevessimo 400 Bad Request aspettare un secondo e inviare esattamente la stessa richiesta difficilmente cambierà il risultato. Infatti la pipeline standard non lo fa: retry e circuit breaker gestiscono solo gli errori 5xx, 408 Request Timeout, 429 Too Many Requests, le HttpRequestException e i timeout.

Ancora più interessante è il caso di POST /payments non idempotente. Se non sappiamo se il primo tentativo sia stato effettivamente processato, eseguire automaticamente la stessa operazione una seconda volta potrebbe significare effettuare due pagamenti.

E qui la pipeline standard non ci protegge: di default ritenta le richieste per qualsiasi metodo HTTP, POST compreso. Se il nostro client esegue operazioni non idempotenti, dobbiamo dirlo esplicitamente:

services
    .AddHttpClient("payments", client =>
    {
        client.BaseAddress = new Uri("https://payments.example.com");
    })
    .AddStandardResilienceHandler(options =>
    {
        // Nessun retry per POST, PUT, PATCH, DELETE e CONNECT
        options.Retry.DisableForUnsafeHttpMethods();
    });

Ogni strategia di resilienza introduce quindi anche dei trade-off.

Persino un retry apparentemente innocuo genera traffico aggiuntivo. Se centinaia di istanze iniziano contemporaneamente a effettuare retry verso un servizio già in difficoltà, possiamo contribuire noi stessi a peggiorare il problema. La pipeline standard mitiga questo rischio con un backoff esponenziale con jitter, che distribuisce nel tempo i tentativi, e con il circuit breaker, che smette di chiamare una dependency chiaramente in difficoltà. Ma mitigare non significa eliminare.

La resilienza, quindi, non significa riprovare sempre. Significa capire quale failure stiamo cercando di gestire e quale comportamento vogliamo ottenere.

E Polly?

Dato che Microsoft.Extensions.Resilience è costruito sopra Polly, vale la pena aprire una piccola parentesi.

Nel luglio 2026 Polly ha annunciato l’adozione dell’Open Source Maintenance Fee (OSMF). Dal 16 novembre 2026, per le organizzazioni che rientrano nei criteri indicati dal progetto (ricavano almeno 20.000 dollari da prodotti che utilizzano Polly), la Maintenance Fee annunciata è di 20 dollari al mese per organizzazione. Il codice continua comunque a essere open source e la licenza di Polly non cambia.

C’è però una distinzione importante: secondo le FAQ per chi usa software soggetto a OSMF, la fee riguarda le dipendenze dirette, non quelle transitive. Se utilizziamo Microsoft.Extensions.Resilience senza referenziare direttamente Polly, Polly rimane una dipendenza transitiva del package Microsoft.

Attenzione però: la distinzione riguarda i package referenziati, non il codice che scriviamo. Usare nel nostro codice tipi di Polly esposti dai package Microsoft, come RetryStrategyOptions o il namespace Polly, non la cambia. Aggiungere un PackageReference esplicito a Polly.Core o Polly.Extensions, invece, rende Polly una dipendenza diretta.

Chi utilizza Polly direttamente dovrà quindi valutare il proprio caso; chi lo utilizza transitivamente attraverso Microsoft.Extensions.Resilience si trova in una situazione differente secondo le regole OSMF attualmente pubblicate.

Chiusa la parentesi, torniamo alla resilience.

Resilience by design

Eravamo partiti da una semplice chiamata. A prima vista sembrava non esserci molto da progettare: mandiamo una richiesta, riceviamo una risposta. Ma appena smettiamo di assumere che tutto andrà sempre bene, dobbiamo decidere come comportarci se la chiamata fallisce, rallenta o mette sotto pressione il servizio esterno.

Una resilience pipeline ci permette di trasformare queste domande in comportamenti espliciti della nostra applicazione.

Il concetto chiave diventa quindi:

Un’applicazione resiliente non è un’applicazione che non fallisce.
È un’applicazione progettata sapendo che qualcosa, prima o poi, fallirà.

Nel prossimo articolo entreremo dentro una resilience pipeline.

Faremo fallire intenzionalmente la nostra chiamata a Catalog API e vedremo, passo dopo passo, come si comportano timeout, retry, circuit breaker, rate limiting e hedging, ma soprattutto quando utilizzarli e quando possono invece peggiorare la situazione.

Suponemos que el servicio externo siempre estará disponible, que la red funcionará, que las respuestas llegarán rápido y que, una vez establecida la comunicación, todo seguirá funcionando igual.

Veamos un ejemplo sencillo:

Normalmente, Catalog API responde en 100 ms y todo funciona perfectamente.

Pero durante unos segundos Catalog API devuelve 503 Service Unavailable. O tarda ocho segundos en responder, deja de responder por completo o se ve desbordada cuando nuestra aplicación recibe diez veces el tráfico previsto.

Una dependencia puede dejar de estar disponible, responder despacio o sobrecargarse. Debemos diseñar el sistema sabiendo que, tarde o temprano, esto ocurrirá.

Aquí entra en juego la resiliencia.

De gestionar errores a diseñar resiliencia

Lo primero que se nos ocurre es gestionar el error:

try
{
    var response = await catalogClient.GetAsync("/products/42");
    response.EnsureSuccessStatusCode();
}
catch (HttpRequestException ex)
{
    // Gestionar el error
}

Este código no tiene nada de malo, pero solo decide qué hacer después de que la operación haya fallado.

Crear una aplicación resiliente exige ir un paso más allá. Debemos preguntarnos:

• ¿Qué ocurre si la llamada falla?
• ¿Qué ocurre si el servicio responde lentamente?
• ¿Qué ocurre si sigue fallando?
• ¿Qué ocurre si enviamos demasiadas peticiones?
• ¿Qué ocurre si el fallo es temporal?

La resiliencia consiste en diseñar explícitamente cómo se comportará la aplicación ante los fallos: recuperarse cuando sea posible y, sobre todo, impedir que un problema en una dependencia se propague al resto del sistema.

Aquí es donde ayuda Microsoft.Extensions.Resilience.

Microsoft.Extensions.Resilience

Si llevas tiempo creando aplicaciones .NET resilientes, probablemente conozcas Polly, una de las bibliotecas más utilizadas en el ecosistema .NET para estrategias como reintentos, circuit breakers y timeouts.

Con .NET 8, Microsoft introdujo dos paquetes construidos sobre Polly v8: Microsoft.Extensions.Resilience y Microsoft.Extensions.Http.Resilience, como explica en su artículo sobre resiliencia en .NET 8.

Hoy disponemos de:

• Microsoft.Extensions.Resilience, que ofrece mecanismos generales para crear e integrar pipelines de resiliencia.
• Microsoft.Extensions.Http.Resilience, que añade funciones específicas para HttpClient.

El paquete anterior, Microsoft.Extensions.Http.Polly, está obsoleto. Microsoft recomienda los paquetes nuevos para aplicaciones nuevas; su documentación de resiliencia en .NET recoge las indicaciones actualizadas.

Si ya conoces Polly, el modelo conceptual te resultará familiar, pues los paquetes de Microsoft se basan en él. Antes de ver el código, conviene entender qué problemas resuelven estas estrategias.

Un resumen de las estrategias

Una pipeline de resiliencia es una secuencia de estrategias que rodean la operación que queremos ejecutar.

Para una llamada HTTP, podemos imaginarla así:

Esta es la pipeline estándar que proporciona Microsoft.Extensions.Http.Resilience. Por orden, contiene un limitador de concurrencia, un timeout global, una estrategia de reintentos, un circuit breaker y un timeout para cada intento.

Por ahora basta con entender la función de cada estrategia:

• El rate limiter controla cuántas operaciones pueden ejecutarse a la vez contra la dependencia. Su valor predeterminado es de 1000 operaciones concurrentes, sin cola. Su objetivo es evitar una presión excesiva sobre el servicio.
• El total timeout limita la duración de toda la operación, incluidos los intentos posteriores.
• La estrategia de retry repite una operación cuando el fallo podría ser transitorio.
• El circuit breaker detiene temporalmente las llamadas cuando la tasa de fallos de una dependencia supera un umbral. Por defecto, ese umbral es el 10 % de las peticiones durante una ventana de 30 segundos, con un mínimo de 100 peticiones.
• El attempt timeout limita la duración de cada intento individual.

La configuración puede ser sorprendentemente sencilla. Después de añadir el paquete:

dotnet add package Microsoft.Extensions.Http.Resilience

basta una línea para añadir el handler estándar:

services
    .AddHttpClient("catalog", client =>
    {
        client.BaseAddress = new Uri("https://catalog.example.com");
    })
    .AddStandardResilienceHandler();

AddStandardResilienceHandler() asocia la pipeline estándar a nuestro HttpClient. Sin embargo, añadir esa línea por sí sola no convierte mágicamente en resiliente a cualquier aplicación.

Reintentar no siempre es buena idea

Supongamos que recibimos 503 Service Unavailable. El problema podría ser temporal, así que reintentar puede tener sentido.

Si recibimos 400 Bad Request, esperar un segundo y enviar la misma petición difícilmente cambiará el resultado. La pipeline estándar no la reintenta: las estrategias de retry y circuit breaker gestionan errores 5xx, 408 Request Timeout, 429 Too Many Requests, HttpRequestException y timeouts.

El caso de un POST /payments no idempotente es más delicado. Si no sabemos si el primer intento se procesó, repetirlo automáticamente podría provocar dos pagos.

La pipeline estándar no nos protege aquí. Por defecto, reintenta peticiones hechas con cualquier método HTTP, incluido POST. Si nuestro cliente realiza operaciones no idempotentes, debemos configurarlo explícitamente:

services
    .AddHttpClient("payments", client =>
    {
        client.BaseAddress = new Uri("https://payments.example.com");
    })
    .AddStandardResilienceHandler(options =>
    {
        // Sin reintentos para POST, PUT, PATCH, DELETE ni CONNECT
        options.Retry.DisableForUnsafeHttpMethods();
    });

Cada estrategia de resiliencia tiene ventajas y costes. Incluso un reintento aparentemente inocuo genera tráfico adicional. Si cientos de instancias reintentan al mismo tiempo contra un servicio que ya tiene problemas, pueden empeorar la situación. La pipeline estándar reduce este riesgo con backoff exponencial y jitter, que distribuyen los intentos en el tiempo, y con un circuit breaker que deja de llamar a una dependencia claramente en dificultades. Reducir el riesgo no significa eliminarlo.

La resiliencia no consiste en reintentarlo todo. Consiste en entender qué fallo quieres gestionar y qué comportamiento buscas.

¿Y Polly?

Como Microsoft.Extensions.Resilience se basa en Polly, hay otro aspecto que conviene tener en cuenta.

En julio de 2026, Polly anunció que adoptaría la Open Source Maintenance Fee (OSMF). A partir del 16 de noviembre de 2026, la cuota anunciada es de 20 dólares al mes por organización para quienes cumplan los criterios del proyecto: al menos 20 000 dólares de ingresos procedentes de productos que utilicen Polly. El código sigue siendo de código abierto y la licencia de Polly no cambia.

Hay una distinción importante: según las preguntas frecuentes de OSMF para consumidores de software, la cuota afecta a las dependencias directas, pero no a las transitivas. Si usamos Microsoft.Extensions.Resilience sin referenciar Polly directamente, Polly sigue siendo una dependencia transitiva del paquete de Microsoft.

La distinción se refiere a los paquetes referenciados, no al código que escribimos. Usar tipos de Polly expuestos por los paquetes de Microsoft, como RetryStrategyOptions o el espacio de nombres Polly, no la altera. En cambio, añadir un PackageReference explícito a Polly.Core o Polly.Extensions convierte Polly en una dependencia directa.

Los equipos que referencien Polly directamente deberán evaluar su caso. Quienes lo utilicen de forma transitiva a través de Microsoft.Extensions.Resilience se encuentran en otra situación según las reglas de OSMF publicadas hasta ahora.

Volvamos a la resiliencia.

Resiliencia desde el diseño

Empezamos con una llamada HTTP sencilla. Al principio parecía que había poco que diseñar: enviamos una petición y recibimos una respuesta. Pero en cuanto dejamos de suponer que todo funcionará siempre, debemos decidir qué ocurre si la llamada falla, se ralentiza o ejerce demasiada presión sobre el servicio externo.

Una pipeline de resiliencia nos permite convertir esas preguntas en comportamientos explícitos de la aplicación.

La idea clave es:

Una aplicación resiliente no es una aplicación que nunca falla.
Es una aplicación diseñada sabiendo que, tarde o temprano, algo fallará.

En el siguiente artículo entraremos en una pipeline de resiliencia. Haremos fallar intencionadamente la llamada a Catalog API y veremos cómo se comportan los timeouts, los reintentos, los circuit breakers, el rate limiting y el hedging: cuándo utilizarlos y cuándo pueden empeorar la situación.

We assume the external service will always be available, the network will work, responses will arrive quickly, and once communication is established, it will keep working the same way.

Consider a simple example:

Normally, Catalog API responds in 100 ms and everything works perfectly.

Then, for a few seconds, Catalog API returns 503 Service Unavailable. Or it takes eight seconds to respond, stops responding altogether, or gets overwhelmed when our application receives ten times its expected traffic.

A dependency can become unavailable, slow, or overloaded. We need to design our system knowing that sooner or later this will happen.

This is where resilience comes in.

From fault handling to resilience

The first instinct is to handle the error:

try
{
    var response = await catalogClient.GetAsync("/products/42");
    response.EnsureSuccessStatusCode();
}
catch (HttpRequestException ex)
{
    // Handle error
}

There is nothing wrong with this code, but it only decides what to do after the operation has failed.

Making an application resilient means going a step further. We need to ask:

• What happens if the call fails?
• What happens if the service is slow?
• What happens if it keeps failing?
• What happens if we send too many requests?
• What happens if the failure is only temporary?

Resilience means explicitly designing how an application behaves when failures occur: recovering where possible and, above all, preventing a problem in one dependency from spreading through the rest of the system.

This is where Microsoft.Extensions.Resilience helps.

Microsoft.Extensions.Resilience

If you have been building resilient .NET applications for a while, you probably know Polly, one of the most widely used .NET libraries for strategies such as retries, circuit breakers, and timeouts.

With .NET 8, Microsoft introduced two packages built on Polly v8: Microsoft.Extensions.Resilience and Microsoft.Extensions.Http.Resilience, as described in its article on .NET 8 resilience.

Today we have:

• Microsoft.Extensions.Resilience, which provides general mechanisms for building and integrating resilience pipelines.
• Microsoft.Extensions.Http.Resilience, which adds features specifically for HttpClient.

The older Microsoft.Extensions.Http.Polly package is deprecated. Microsoft recommends the newer packages for new applications; its .NET resilience documentation has the current guidance.

The conceptual model will feel familiar if you have used Polly, since the Microsoft packages are built on it. Before looking at code, let’s see what problems these strategies solve.

An overview of the strategies

A resilience pipeline is a sequence of strategies wrapped around the operation we want to execute.

For an HTTP call, we can picture it like this:

This is the standard pipeline provided by Microsoft.Extensions.Http.Resilience. In order, it contains a rate limiter, an overall timeout, a retry strategy, a circuit breaker, and a timeout for each attempt.

For now, a high-level understanding of each strategy is enough:

• The rate limiter controls how many operations can run concurrently against the dependency. Its default is 1,000 concurrent operations with no queue. The aim is to avoid putting excessive pressure on the called service.
• The total timeout limits the whole operation, including any subsequent attempts.
• The retry strategy repeats an operation when a failure might be transient.
• The circuit breaker temporarily stops calls when the failure rate for a dependency exceeds a threshold. By default, that threshold is 10% of requests within a 30-second window, with at least 100 requests.
• The attempt timeout limits the duration of each individual attempt.

Configuration can be surprisingly simple. After adding the package:

dotnet add package Microsoft.Extensions.Http.Resilience

one line adds the standard handler:

services
    .AddHttpClient("catalog", client =>
    {
        client.BaseAddress = new Uri("https://catalog.example.com");
    })
    .AddStandardResilienceHandler();

AddStandardResilienceHandler() attaches the standard pipeline to our HttpClient. Adding that line alone, however, does not magically make every application resilient.

Retrying is not always a good idea

Suppose we receive 503 Service Unavailable. The problem may be temporary, so retrying can make sense.

If we receive 400 Bad Request, waiting a second and sending the same request again is unlikely to change the result. The standard pipeline does not retry it: retry and circuit-breaker strategies handle 5xx, 408 Request Timeout, 429 Too Many Requests, HttpRequestException, and timeouts.

The case of a non-idempotent POST /payments is more interesting. If we do not know whether the first attempt was processed, automatically repeating it might result in two payments.

The standard pipeline does not protect us here. By default, it retries requests made with any HTTP method, including POST. If our client performs non-idempotent operations, we must configure this explicitly:

services
    .AddHttpClient("payments", client =>
    {
        client.BaseAddress = new Uri("https://payments.example.com");
    })
    .AddStandardResilienceHandler(options =>
    {
        // No retries for POST, PUT, PATCH, DELETE, or CONNECT
        options.Retry.DisableForUnsafeHttpMethods();
    });

Every resilience strategy introduces trade-offs. Even an apparently harmless retry adds traffic. If hundreds of instances retry at the same time against a struggling service, they can make its problems worse. The standard pipeline reduces this risk through exponential backoff with jitter, which spreads attempts over time, and a circuit breaker that stops calling a clearly struggling dependency. Reducing the risk does not eliminate it.

Resilience does not mean retrying everything. It means understanding the failure you are trying to handle and the behavior you want.

What about Polly?

Because Microsoft.Extensions.Resilience is built on Polly, there is one more point to consider.

In July 2026, Polly announced its adoption of the Open Source Maintenance Fee (OSMF). Starting November 16, 2026, the announced fee is US$20 per month per organization for those meeting the project’s criteria: at least US$20,000 in revenue from products that use Polly. The code remains open source and Polly’s license does not change.

There is an important distinction: according to the OSMF FAQ for software consumers, the fee concerns direct dependencies, not transitive ones. If we use Microsoft.Extensions.Resilience without referencing Polly directly, Polly remains a transitive dependency of the Microsoft package.

The distinction concerns referenced packages, not the code we write. Using Polly types exposed by the Microsoft packages, such as RetryStrategyOptions or the Polly namespace, does not change it. Adding an explicit PackageReference to Polly.Core or Polly.Extensions does make Polly a direct dependency.

Teams that reference Polly directly need to assess their own case. Teams that use it transitively through Microsoft.Extensions.Resilience are in a different position under the OSMF rules currently published.

With that aside, let’s return to resilience.

Resilience by design

We started with a simple HTTP call. At first, there seemed to be little to design: send a request, receive a response. Once we stop assuming everything will always work, however, we have to decide what happens if the call fails, slows down, or puts pressure on the external service.

A resilience pipeline lets us turn these questions into explicit application behavior.

The key idea is:

A resilient application is not one that never fails.
It is one designed with the knowledge that something will eventually fail.

In the next article we will step inside a resilience pipeline. We will deliberately make our call to Catalog API fail and examine timeouts, retries, circuit breakers, rate limiting, and hedging: how they behave, when to use them, and when they can make things worse.

En los artículos anteriores de la serie vimos qué es MCP y cómo construir un servidor en .NET (ambos en italiano). Aquí veremos qué ha cambiado y por qué.

El paso de un modelo con estado a uno sin estado

El cambio más importante es el paso de un modelo con estado a uno sin estado. Todos los demás cambios, grandes y pequeños, se derivan de él.

Al principio, el protocolo se diseñó principalmente para conectar procesos locales mediante una tubería, donde cliente y servidor pueden escribir en cualquier momento. Esa simetría no existe en HTTP: el cliente habla y el servidor responde. Para permitir también la comunicación del servidor al cliente, se introdujeron mecanismos específicos: una sesión que permanecía abierta, identificada mediante Mcp-Session-Id, por la que el servidor podía enviar mensajes cuando los necesitara.

Esto tiene dos costes. El primero es la necesidad de mantener el estado. El segundo, más molesto, es que la solicitud del cliente queda vinculada a la instancia concreta del servidor que abrió la sesión. Esto dificulta el escalado: el balanceador de carga debe enviar siempre al mismo cliente a la misma instancia y, si esta falla, la sesión desaparece con ella.

La nueva revisión cambia este flujo para adaptarse mejor a HTTP y, sobre todo, mejorar la escalabilidad y la fiabilidad.

MRTR: Multi Round-Trip Requests

Si el servidor necesita información del cliente, simplemente responde: en su respuesta pide lo que necesita y termina el intercambio. Una vez obtenida la información, el cliente vuelve a llamar al servidor con la misma solicitud, ampliada con la respuesta.

Veamos un ejemplo concreto. La herramienta close_ticket cierra un ticket de soporte, pero primero pide confirmar el motivo. Es el caso más sencillo que requiere una interacción a mitad de la llamada, y precisamente donde divergen las dos revisiones.

En la ronda 1, el cliente llama a tools/call. El servidor todavía no conoce el motivo del cierre, así que no puede terminar el trabajo. Responde con resultType: input_required, la pregunta que debe trasladarse al usuario y un requestState. La llamada HTTP termina aquí: el servidor libera la conexión, el controlador finaliza y no queda nada en memoria. El requestState es el único vínculo entre las dos rondas. Lo genera el servidor y el cliente lo devuelve sin modificarlo.

En la ronda 2, el cliente repite la misma llamada tools/call, añadiendo el requestState recibido y la respuesta del usuario dentro de inputResponses. Esta vez el servidor tiene todo lo necesario y termina con resultType: complete.

El campo clave es resultType: input_required significa «me falta algo, vuelve a llamarme»; complete indica que el intercambio ha terminado.

La diferencia entre los dos modelos se aprecia enseguida en las trazas de la misma herramienta, ejecutada primero con una sesión y después con MRTR.

Con sesión: 26 spans, profundidad 8. Se ven initialize, elicitation/create anidada dentro de tools/call y el DELETE final que cierra la sesión. Entre medias hay un GET / que dura por sí solo 0,15 segundos en una traza de 0,37 segundos: es el canal del servidor al cliente, abierto durante toda la sesión.

Con MRTR: 19 spans, profundidad 4. Las dos llamadas tools/call están al mismo nivel, no una dentro de la otra. No hay barra GET ni DELETE.

La diferencia de profundidad muestra el cambio de enfoque: antes una llamada contenía una conversación; ahora hay dos llamadas independientes.

Adiós al intercambio inicial

Como parte del paso a un modelo sin estado, también se ha eliminado el mecanismo de inicialización: el intercambio initialize/notifications/initialized y Mcp-Session-Id dejan paso a solicitudes independientes.

El intercambio inicial cumplía dos funciones, y cada una ha seguido un camino distinto.

La información del cliente — versión del protocolo, capacidades e identidad — servía para que el servidor supiera con quién estaba hablando. Ahora viaja en cada solicitud dentro de _meta, bajo tres claves:

io.modelcontextprotocol/protocolVersion
io.modelcontextprotocol/clientCapabilities
io.modelcontextprotocol/clientInfo

Se trata, literalmente, del contenido de initialize repetido en cada solicitud. Y estos campos son obligatorios: si falta alguno, el servidor rechaza la solicitud.

{"error":{"code":-32602,"message":
  "Requests using protocol version '2026-07-28' must include
   '_meta/io.modelcontextprotocol/protocolVersion'."}}

La información del servidor — serverInfo y serverCapabilities — permitía al cliente saber qué podía hacer el servidor. Ahora es una solicitud ordinaria, server/discover, y es opcional: un cliente que ya sabe qué herramienta necesita puede omitirla e ir directamente a tools/call.

Se pasa así de una negociación, en la que ambas partes llegaban a un acuerdo y lo recordaban, a una declaración repetida en cada solicitud.

Los demás cambios

• Enrutamiento basado en cabeceras. Se introducen Mcp-Method y Mcp-Name. Como todas las solicitudes son POST al mismo endpoint, antes un proxy tenía que leer y analizar el cuerpo JSON para enrutarlas. Ahora le bastan dos cabeceras.
• Listas que se pueden almacenar en caché. Las respuestas de tools/list, prompts/list, resources/list y resources/read incluyen ahora ttlMs y cacheScope: el cliente sabe durante cuánto tiempo puede guardarlas y con qué alcance. Sin depender de una sesión, la caché resulta posible.
• Roots y Sampling en desuso. Eran solicitudes iniciadas por el servidor hacia el cliente. Seguirán funcionando durante al menos doce meses, pero las nuevas implementaciones deberían evitar adoptarlas.
• Logging en desuso. Era una notificación, no una pregunta a la espera de respuesta, así que ni siquiera puede utilizar MRTR. La solución pasa a ser OpenTelemetry; si quieres profundizar, consulta la serie dedicada en este blog.
• Elicitation sigue vigente. No se ha dejado de usar: solo cambia el mecanismo de comunicación y se convierte en el principal caso de uso de MRTR.
• Autorización. También hay novedades aquí, pero merecen un artículo propio.

Ventajas, inconvenientes y aspectos a vigilar

Como ocurre con cualquier cambio, hay ventajas, inconvenientes y detalles que requieren atención.

El sistema escala mejor, pero las rondas adicionales aumentan la latencia: una interacción que antes cabía en una llamada ahora necesita dos. En una red local pueden ser milisegundos; en una conexión lenta, bastante más.

Sobre todo, debemos prestar atención a cómo escribimos el servidor, porque ahora hay que gestionar la idempotencia.

Conclusión

MCP ha pasado de «el servidor puede volver a llamar al cliente en mitad de una solicitud» a «el servidor responde y se olvida de ti». El fin de las sesiones, las nuevas cabeceras, las listas que se pueden almacenar en caché y las funciones en desuso se derivan de esta decisión.

El precio son algunas rondas adicionales y la responsabilidad de gestionar la idempotencia. A cambio, el servidor puede situarse detrás de un balanceador de carga corriente sin una configuración especial y reiniciarse sin efectos drásticos sobre las conversaciones en curso.

En el próximo artículo pasaremos a la práctica: cómo escribir en .NET un servidor para la nueva revisión y migrar los antiguos (en italiano). Actualizar el paquete compila sin avisos, pero después falla en tiempo de ejecución.

Recursos útiles

• Anuncio oficial de la revisión 2026-07-28
• Documentación oficial de MCP

Earlier articles in this series covered what MCP is and how to build a server in .NET (both in Italian). Here we look at what changed and why.

From stateful to stateless

The biggest change is the move from stateful to stateless operation. All the other changes, large and small, follow from it.

MCP was originally designed mainly to connect local processes through a pipe, where client and server can each write whenever they want. HTTP does not have that symmetry: the client speaks and the server replies. To enable server-to-client communication anyway, the protocol introduced a persistent session, identified by an Mcp-Session-Id, through which the server could send messages as needed.

This has two costs. First, you have to maintain state. Second, and more troublesome, a client request becomes tied to the particular server instance that opened the session. That makes scaling harder: the load balancer must keep routing a client to the same instance, and the session dies if that instance fails.

The new revision changes this flow to fit HTTP better and, above all, to improve scalability and reliability.

MRTR: Multi Round-Trip Requests

If the server needs information from the client, it simply responds: its response asks for what it needs and ends the exchange. Once the client has gathered the information, it calls the server again with the same request, supplemented by the answer.

Consider a concrete example. The close_ticket tool closes a support ticket, but first asks the user to confirm the reason. This is the smallest case that needs an interaction in the middle of a call, and exactly where the two revisions diverge.

In round 1, the client calls tools/call. The server does not have the closing reason, so it cannot finish the job. It responds with resultType: input_required, a question for the user, and a requestState. The HTTP call ends here: the server releases the connection, the handler finishes, and nothing remains in memory. The requestState is the only continuity between the two rounds. The server produces it, and the client sends it back unchanged.

In round 2, the client repeats the same tools/call, adding the received requestState and the user’s answer in inputResponses. Now the server has everything it needs and finishes with resultType: complete.

The field to watch is resultType: input_required means “I need something else; call me again,” while complete means the exchange is over.

You can see the difference at a glance in the traces of the very same tool, run first with a session and then with MRTR.

With a session: 26 spans, depth 8. You can see initialize, elicitation/create nested inside tools/call, and the final DELETE that tears down the session. In between, a GET / lasts 0.15 seconds on a 0.37-second trace: that is the server-to-client channel, open for the whole session.

With MRTR: 19 spans, depth 4. The two tools/call calls are siblings, not one nested inside the other. There is no GET bar and no DELETE.

The change in depth makes the shift in approach visible: one call used to contain a conversation; now there are two independent calls.

Goodbye handshake

As part of the move to stateless operation, the initialization mechanism is gone too: the initialize/notifications/initialized exchange and Mcp-Session-Id give way to standalone requests.

The handshake did two jobs, and those jobs have taken different paths.

Client information — protocol version, capabilities, and identity — told the server whom it was talking to. It now travels with every request inside _meta, under three keys:

io.modelcontextprotocol/protocolVersion
io.modelcontextprotocol/clientCapabilities
io.modelcontextprotocol/clientInfo

This is, quite literally, the content of initialize repeated in every request. These fields are mandatory: if one is missing, the server rejects the request.

{"error":{"code":-32602,"message":
  "Requests using protocol version '2026-07-28' must include
   '_meta/io.modelcontextprotocol/protocolVersion'."}}

Server information — serverInfo and serverCapabilities — let the client learn what the server could do. This is now an ordinary, optional server/discover request: a client that already knows which tool to call can skip it and go straight to tools/call.

In other words, a negotiation in which both sides agreed and remembered the result has become a declaration repeated in every request.

The other changes

• Header-based routing. Mcp-Method and Mcp-Name have been introduced. Since requests all use POST to the same endpoint, a proxy previously had to read and parse the JSON body to route them. Now two headers are enough.
• Cacheable lists. Responses from tools/list, prompts/list, resources/list, and resources/read now carry ttlMs and cacheScope, telling the client how long and within what scope to cache them. Without a session to depend on, caching becomes possible.
• Roots and Sampling deprecated. These were requests initiated by the server toward the client. They will keep working for at least twelve months, but new implementations should avoid adopting them.
• Logging deprecated. Logging was a notification, not a question awaiting an answer, so it cannot even use MRTR. OpenTelemetry is the solution here; if you want to explore it, see the dedicated series on this blog.
• Elicitation remains. It has not been deprecated: only its transport changes, and it becomes the main use case for MRTR.
• Authorization. There are changes here too, but they deserve an article of their own.

Pros, cons, and what to watch for

As with any change, there are trade-offs and details that need attention.

The system scales more easily, but extra round trips add latency: an interaction that used to fit in one call now needs two. On a local network that may mean milliseconds; on a slow connection, much more.

Most of all, we need to pay attention to how we write the server, because idempotency now needs to be handled.

Conclusion

MCP has moved from “the server can call back to the client in the middle of a request” to “the server replies and forgets about you.” The end of sessions, new headers, cacheable lists, and deprecated features all follow from that decision.

The price is a few more round trips and the responsibility of handling idempotency. In return, a server can sit behind an ordinary load balancer without special configuration and restart without drastic effects on ongoing conversations.

The next article gets practical: how to write a .NET server for the new revision and migrate older servers (in Italian). Simply upgrading the package compiles without a warning, then breaks at runtime.

Useful resources

• Official announcement of the 2026-07-28 revision
• Official MCP documentation

Il codice completo è su GitHub.

Il progetto

Serve il .NET 10 SDK. Partiamo da un progetto web vuoto e aggiungiamo il pacchetto:

dotnet new web -n MCP_Server_MRTR
cd MCP_Server_MRTR
dotnet add package ModelContextProtocol.AspNetCore

Al momento in cui scrivo la versione stabile è la 2.2.0. La 2.0.0 è uscita il 28 luglio 2026, lo stesso giorno della revisione del protocollo.

Il server

Questo è tutto il Program.cs:

using TicketServer.Tools;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddMcpServer()
    .WithHttpTransport()
    .WithTools<TicketTools>();

var app = builder.Build();

app.MapMcp();

app.Run();

Se hai letto la guida al primo server ti sembrerà identico a prima, e infatti lo è. La cosa interessante è quello che non c’è: nessuna configurazione per lo stateless, perché dalla 2.x è il default. HttpServerTransportOptions.Stateless vale true se non lo tocchi.

Vale la pena fermarsi un secondo. Il server che scala, quello che puoi mettere dietro un load balancer qualsiasi e riavviare senza pensarci, è quello che ottieni non scrivendo niente. Il caso che richiede configurazione esplicita ora è l’altro.

Il tool che deve chiedere qualcosa

L’esempio è lo stesso dell’articolo precedente: close_ticket chiude un ticket di assistenza, ma prima vuole farsi confermare il motivo.

Il tool ha tre strade, e conviene leggerle nell’ordine in cui il codice le incontra. Se il chiamante ha già passato il motivo non c’è niente da chiedere: un round e via. Se il motivo manca, il tool solleva una InputRequiredException — che non è un errore: l’SDK la trasforma in un risultato con resultType: "input_required", e la chiamata HTTP finisce lì. Se il client torna con la risposta, la trova in context.Params.InputResponses.

[McpServerToolType]
public class TicketTools
{
    private const string DefaultCloseReason = "completed";

    [McpServerTool(Name = "close_ticket")]
    [Description("Chiude un ticket di assistenza registrando il motivo.")]
    public static string CloseTicket(
        McpServer server,
        RequestContext<CallToolRequestParams> context,
        [Description("L'ID del ticket da chiudere")] long ticketId,
        [Description("Il motivo della chiusura")] string? closeReason = null)
    {
        // Round 2: il client è tornato con la risposta
        if (context.Params?.InputResponses?.TryGetValue("closeReason", out var response) is true)
        {
            var elicited = response.Deserialize(InputResponse.ElicitResultJsonTypeInfo);

            if (elicited?.IsAccepted is not true)
            {
                return "Chiusura annullata";
            }

            var confirmed = elicited.Content?.TryGetValue("closeReason", out var value) is true
                ? value.GetString()
                : null;

            return Close(ticketId, confirmed);
        }

        // Il chiamante aveva già tutto: un solo round
        if (!string.IsNullOrWhiteSpace(closeReason))
        {
            return Close(ticketId, closeReason);
        }

        // Round 1: chiedi, poi togliti di mezzo
        if (server.IsMrtrSupported)
        {
            throw new InputRequiredException(
                inputRequests: new Dictionary<string, InputRequest>
                {
                    ["closeReason"] = InputRequest.ForElicitation(new ElicitRequestParams
                    {
                        Message = $"Chiudere il ticket {ticketId}?",
                        RequestedSchema = new()
                        {
                            Properties =
                            {
                                ["closeReason"] = new ElicitRequestParams.StringSchema
                                {
                                    Title = "Motivo di chiusura",
                                    Default = DefaultCloseReason,
                                },
                            },
                        },
                    }),
                },
                requestState: ticketId.ToString());
        }

        // Un client vecchio senza sessione non può essere interrogato
        return "Per chiudere un ticket serve un motivo: richiama passando `closeReason`.";
    }

    private static string Close(long ticketId, string? reason)
    {
        reason = string.IsNullOrWhiteSpace(reason) ? DefaultCloseReason : reason;
        return $"Ticket {ticketId} chiuso: {reason}";
    }
}

Il requestState è la sola cosa che lega i due round. Lo produce il server, il client lo rimanda indietro senza guardarci dentro.

Provarlo

Brutta notizia per chi si era abituato a MCP Inspector: non sa ancora eseguire MRTR. Il suo client per la revisione 2026 è in preview e sui risultati input_required si ferma con un errore invece di gestirli.

Serve quindi un client vero, che sono una quarantina di righe. La parte che conta è l’handler:

var options = new McpClientOptions
{
    Handlers = new McpClientHandlers
    {
        ElicitationHandler = (requestParams, ct) =>
        {
            Console.WriteLine($"  [richiesta] {requestParams?.Message}");

            return ValueTask.FromResult(new ElicitResult
            {
                Action = "accept",
                Content = new Dictionary<string, JsonElement>
                {
                    ["closeReason"] = JsonSerializer.SerializeToElement("duplicato"),
                },
            });
        },
    },
};

await using var client = await McpClient.CreateAsync(transport, options);

var result = await client.CallToolAsync(
    "close_ticket",
    new Dictionary<string, object?> { ["ticketId"] = 1234L });

Nota cosa non c’è: il round 2. Chiamiamo il tool una volta sola. L’SDK client riceve input_required, usa l’handler per procurarsi la risposta e rifà da solo la stessa tools/call allegando requestState e inputResponses.

connessione a http://localhost:5250/
  [tools] close_ticket
  [richiesta] Chiudere il ticket 1234?
  [risultato] Ticket 1234 chiuso: duplicato

La prima risposta, quella che chiude il round 1, è questa:

{
  "result": {
    "inputRequests": { "closeReason": { "method": "elicitation/create", ... } },
    "requestState": "1234",
    "resultType": "input_required",
    "_meta": {
      "io.modelcontextprotocol/serverInfo": {
        "name": "MCP_Server_MRTR", "version": "1.0.0.0"
      }
    }
  },
  "id": 1, "jsonrpc": "2.0"
}

C’è una simmetria che vale la pena notare: l’identità del client sale nel _meta di ogni richiesta, quella del server torna nel _meta di ogni risposta. Quello che prima veniva scambiato una volta con initialize e poi ricordato, ora viene ripetuto e dimenticato.

Migrare un server che esiste già

Fin qui il campo era libero. Vediamo ora cosa succede a un server 1.x, dove lo stesso tool era scritto nell’unico modo che la 1.x permetteva:

public static async Task<string> CloseTicketAsync(
    McpServer server, long ticketId, CancellationToken cancellationToken)
{
    var result = await server.ElicitAsync(
        new ElicitRequestParams { Message = $"Chiudere il ticket {ticketId}?", ... },
        cancellationToken);

    if (!result.IsAccepted) return "Chiusura annullata";
    // ...
}

Quell’await è il punto. Il server manda elicitation/create giù per lo stream GET che il client tiene aperto e aspetta: l’handler, la sessione e questo specifico processo restano vivi per tutto il tempo che la persona impiega a decidere.

Passo 1: alza il pacchetto

dotnet add package ModelContextProtocol.AspNetCore

Dalla 1.4.1 alla 2.2.0. Ricompiliamo:

Compilazione completata.
    Errori: 0

Zero errori e zero warning. Nessun MCP9005, nessun CS. Niente ti dice che qualcosa è cambiato.

Passo 2: eseguilo

Il server parte, il client si connette, tools/list risponde. E poi:

  [tools] close_ticket
  [risultato] An error occurred invoking 'close_ticket'.

Nei log del server:

fail: ModelContextProtocol.Server.McpServer
      "close_ticket" threw an unhandled exception.
      System.InvalidOperationException: Elicitation is not supported in stateless mode.
         at McpServer.ThrowIfElicitationUnsupported(ElicitRequestParams request)
         at McpServer.ElicitAsync(ElicitRequestParams requestParams, CancellationToken ct)

Perché succede

Perché è cambiato un default. Nella 1.x il trasporto HTTP era stateful se non dicevi niente; dalla 2.x è stateless se non dici niente. Il tuo codice non nominava Stateless — non serviva, era già quello che volevi — quindi il significato di quella riga mancante si è ribaltato sotto i piedi. E in modalità stateless il server non ha nessun canale su cui raggiungere il client.

Le due strade

La scorciatoia è rimettere le sessioni, e il server riparte:

.WithHttpTransport(options => { options.Stateless = false; })

Funziona davvero, l’ho verificato. Ma hai alzato il pacchetto e tenuto tutto quello che rendeva il modello vecchio poco scalabile. Come passo intermedio per sbloccare un deploy va benissimo; come destinazione, no.

La migrazione vera è riscrivere il tool nella forma vista sopra. Il confronto con la versione 1.x dice tre cose:

• Il metodo non è più async. Non aspetta più niente: chiede e termina. Sparisce anche il CancellationToken, che serviva a interrompere l’attesa.
• Lo schema dell’elicitation non cambia. È lo stesso ElicitRequestParams, solo consegnato in un altro modo: prima come argomento di ElicitAsync, ora dentro InputRequest.ForElicitation. L’elicitation non è deprecata, è cambiato il veicolo.
• È comparso IsMrtrSupported. Serve a non lasciare in un vicolo cieco i client che non ce la fanno.

I warning che invece esistono

Il caso che abbiamo visto non ne produce nessuno, ma ci sono API che l’SDK segnala: MCP9004 per EnableLegacySse, MCP9005 per Roots, Sampling e Logging (funzionano ancora per almeno dodici mesi, ma le nuove implementazioni non dovrebbero adottarle), MCP9006 per le opzioni che hanno senso solo con le sessioni come EventStreamStore e IdleTimeout, MCP9007 per AuthorizationRedirectDelegate.

Se nel tuo .csproj c’è un NoWarn che elenca questi codici, quella lista è la tua to-do list di migrazione: si cancella una voce alla volta finché non resta niente.

Tre cose a cui fare attenzione

Gli effetti collaterali vanno dopo la domanda. Il round 1 e il round 2 sono due chiamate allo stesso tool con gli stessi argomenti: tutto quello che il tool fa prima di sollevare InputRequiredException viene eseguito due volte. Nel codice sopra il metodo Close sta dopo, ed è deliberato. Nella versione 1.x il codice prima dell’await girava una volta sola, quindi la migrazione può trasformare in doppioni cose che prima erano innocue.

Il requestState è input non fidato. Torna dal client, e il client può averlo modificato. Nell’esempio è un ID di ticket e il danno è limitato, ma se ci metti qualcosa che decide un’autorizzazione, firmalo.

Controlla IsMrtrSupported. Un client vecchio che parla con un server stateless non può essere interrogato: non c’è nessun canale su cui raggiungerlo. Il ramo di fallback non deve fare miracoli, basta che dica cosa manca.

Conclusioni

Il server nuovo è più semplice del vecchio, non più complicato: stateless è il default, il trasporto non si configura, e il tool non deve tenersi stretto niente fra un round e l’altro.

La migrazione, invece, è insidiosa proprio perché non fa rumore. Non è quella che non compila: è questa, che compila pulita e si rompe solo sul percorso che a nessuno viene in mente di testare. Se hai un server 1.x con un ElicitAsync dentro, cercalo prima di alzare il pacchetto — e prova davvero il tool che fa la domanda, non solo tools/list.

Risorse utili

• Codice completo su GitHub
• Annuncio dell’SDK C# v2.0
• La revisione 2026-07-28

Nei precedenti articoli della serie abbiamo visto cos’è MCP e come costruire un server in .NET. Qui vediamo cosa è cambiato e perché.

Il cambio da stateful a stateless

Il più grande cambiamento è il passaggio da stateful a stateless. Tutti gli altri cambiamenti, grandi e piccoli, discendono da lì.

Quando il protocollo è nato, il suo scopo era principalmente quello di collegare processi locali attraverso una pipe, dove client e server possono scriversi quando vogliono. Quella simmetria su HTTP non esiste: parla il client, risponde il server. Per rendere comunque possibile la comunicazione server → client, erano stati introdotti dei meccanismi appositi: una sessione tenuta aperta, identificata da un Mcp-Session-Id, su cui il server poteva scrivere quando ne aveva bisogno.

Questo ha due costi. Il primo è che bisogna mantenere lo stato. Il secondo, più fastidioso, è che lega la richiesta del client all’istanza esatta del server che ha aperto quella sessione, e questo non permette di scalare: serve che il load balancer mandi sempre lo stesso client alla stessa istanza, e se quella cade, la sessione muore con lei.

La nuova versione interrompe questo flusso per sposarsi al meglio con HTTP e soprattutto per garantire scalabilità e affidabilità.

MRTR: Multi Round-Trip Requests

Se il server ha bisogno di informazioni dal client, semplicemente risponde: nella risposta chiede quello che gli serve e chiude la comunicazione. Il client, una volta ottenute le informazioni necessarie, richiama il server con la stessa chiamata arricchita della risposta.

Facciamo un esempio concreto. Il tool è close_ticket: chiude un ticket di assistenza, ma prima vuole farsi confermare il motivo. È il caso minimo che richiede un’interazione a metà chiamata, ed è esattamente il punto in cui le due revisioni divergono.

Nel round 1 il client chiama tools/call. Il server non ha il motivo di chiusura, quindi non arriva in fondo al lavoro: risponde con resultType: input_required, la domanda da girare all’utente e un requestState. La chiamata HTTP finisce qui: il server lascia andare la connessione, l’handler termina, in memoria non resta niente. Il requestState è la sola continuità fra i due round, lo produce il server e il client lo rimanda indietro così com’è.

Nel round 2 il client ripete la stessa tools/call, aggiungendo il requestState ricevuto e la risposta dell’utente dentro inputResponses. Questa volta il server ha tutto quello che gli serve e chiude con resultType: complete.

Il campo da guardare è proprio resultType: input_required significa “mi manca qualcosa, richiamami”, complete che il giro è finito.

La differenza fra i due mondi si legge a colpo d’occhio nelle tracce dello stesso identico tool, eseguito prima con una sessione e poi in MRTR.

Con la sessione: 26 span, profondità 8. Si vedono l’initialize, l’elicitation/create annidata dentro il tools/call e il DELETE finale che smonta la sessione. In mezzo c’è un GET / che da solo dura 0,15s su una traccia di 0,37s: è il canale server → client, aperto per tutta la sessione.

Con MRTR: 19 span, profondità 4. I due tools/call sono fratelli, non uno dentro l’altro. Nessuna barra GET, nessun DELETE.

La differenza di profondità è il cambio di filosofia reso visibile: prima una chiamata conteneva una conversazione, ora sono due chiamate indipendenti.

Addio handshake

Sempre nell’ottica dello stateless, è stato rimosso anche il meccanismo di inizializzazione: l’exchange initialize/notifications/initialized e l’Mcp-Session-Id lasciano il posto a richieste standalone.

L’handshake faceva due lavori, e i due lavori hanno preso strade opposte.

La parte client — versione del protocollo, capability e identità — serviva al server per sapere con chi stava parlando. Ora viaggia in ogni richiesta dentro _meta, sotto tre chiavi:

io.modelcontextprotocol/protocolVersion
io.modelcontextprotocol/clientCapabilities
io.modelcontextprotocol/clientInfo

Sono, letteralmente, il contenuto dell’initialize spalmato su ogni richiesta. E non sono facoltative: se ne manca una, il server rifiuta la richiesta.

{"error":{"code":-32602,"message":
  "Requests using protocol version '2026-07-28' must include
   '_meta/io.modelcontextprotocol/protocolVersion'."}}

La parte server — serverInfo e serverCapabilities — permetteva al client di sapere che cosa era in grado di fare il server. Ora è diventata una richiesta ordinaria, server/discover, ed è facoltativa: un client che sa già quale tool vuole chiamare può saltarla e andare dritto al tools/call.

Si passa quindi da una negoziazione, con due parti che si mettono d’accordo e ricordano l’accordo, a una dichiarazione ripetuta a ogni richiesta.

Le altre modifiche

• Routing basato su header. Sono stati introdotti Mcp-Method e Mcp-Name. Dato che è tutto basato su POST verso lo stesso endpoint, un proxy che avesse voluto instradare le richieste avrebbe dovuto leggere e analizzare il body JSON: ora gli bastano due header.
• Liste cacheabili. Le risposte di tools/list, prompts/list, resources/list e resources/read portano ora ttlMs e cacheScope: il client sa per quanto tenerle e con che ambito. Senza una sessione da cui dipendere, la cache diventa possibile.
• Roots e Sampling deprecate. Erano richieste che partivano dal server verso il client. Continuano a funzionare per almeno dodici mesi, ma le nuove implementazioni non dovrebbero adottarle.
• Logging deprecato. Era una notifica e non una domanda in attesa di risposta, quindi non potrebbe nemmeno avere un veicolo MRTR. La soluzione diventa, giustamente, OpenTelemetry — e se vuoi approfondire, c’è la serie dedicata su questo blog.
• Elicitation viva. Non è deprecata: cambia solo il veicolo, e diventa il caso d’uso principale di MRTR.
• Autorizzazione. Anche qui ci sono novità, ma sono abbastanza corpose da meritare un articolo a parte.

Pro, contro e a cosa fare attenzione

Come in tutte le cose, ci sono pro e contro, e punti su cui bisogna prestare attenzione.

A fronte di una maggiore scalabilità del sistema, abbiamo più round-trip, quindi più latenza: un’interazione che prima stava dentro una chiamata ora ne richiede due. Su una rete locale si parla di millisecondi, su una connessione lenta di molto di più.

E soprattutto dobbiamo prestare attenzione a come scriviamo il server, perché da ora in avanti va gestita l’idempotenza.

Conclusioni

MCP è passato da “il server può richiamare il client nel mezzo di una chiamata” a “il server risponde e si dimentica di te”. La fine delle sessioni, gli header nuovi, le liste cacheabili e le feature deprecate discendono tutti da questa scelta.

Il prezzo è qualche round-trip in più e la responsabilità dell’idempotenza. Quello che si ottiene è un server che si mette dietro un load balancer qualsiasi senza configurazioni particolari, e che può essere riavviato senza effetti drastici sulle conversazioni in corso.

Nel prossimo articolo passiamo alla pratica: come scrivere in .NET un server con la nuova revisione e come migrare quelli vecchi — perché alzare il pacchetto compila senza un warning e poi si rompe a runtime.

Risorse utili

• Annuncio ufficiale della revisione 2026-07-28
• Documentazione ufficiale MCP

Prima dei Keyed Services, registrare più implementazioni della stessa interfaccia e scegliere quale iniettare richiedeva workaround: factory manuali, risoluzione tramite IEnumerable<T> con filtro LINQ, o container di terze parti come Autofac. Era un’operazione comune — pensate a scenari con più provider di cache, più strategy di notifica, o più implementazioni di un gateway di pagamento — ma il container nativo non la supportava direttamente.

I Keyed Services risolvono il problema permettendo di associare una chiave a ogni registrazione e di specificare quale implementazione iniettare tramite l’attributo [FromKeyedServices]. Non serve più filtrare a runtime o costruire factory ad hoc: la scelta dell’implementazione è dichiarativa e avviene al momento della risoluzione.

Registrazione e risoluzione

La registrazione avviene con i metodi AddKeyed{Lifetime}, passando una chiave come primo parametro:

var services = new ServiceCollection();
services.AddKeyedSingleton<ICache, RedisCache>("redis");
services.AddKeyedSingleton<ICache, MemoryCache>("memory");

Per iniettare una specifica implementazione, si usa l’attributo [FromKeyedServices] nel costruttore del servizio che ne ha bisogno:

public class ProductService(
    [FromKeyedServices("redis")] ICache cache)
{
    public string GetProducts() => cache.Get("products");
}

Il container sa quale ICache fornire perché la chiave "redis" nella richiesta corrisponde a quella usata nella registrazione. In Minimal API la stessa risoluzione avviene direttamente nei parametri dell’endpoint:

app.MapGet("/products", ([FromKeyedServices("memory")] ICache cache) =>
{
    return cache.Get("products");
});

La risoluzione manuale dal service provider usa GetRequiredKeyedService:

var redis = provider.GetRequiredKeyedService<ICache>("redis");
var memory = provider.GetRequiredKeyedService<ICache>("memory");

Un dettaglio importante: la chiave non è limitata a string. Può essere qualsiasi object che implementa correttamente Equals — int, enum, record, o qualsiasi tipo custom. Questo apre possibilità interessanti che vedremo nella sezione sulle best practice.

AnyKey: registrazione fallback

KeyedService.AnyKey è un valore speciale che permette di registrare un’implementazione di default. Quando il container riceve una richiesta per una chiave che non ha una registrazione esplicita, usa la registrazione AnyKey come fallback:

var services = new ServiceCollection();
services.AddKeyedSingleton<ICache, PremiumCache>("premium");
services.AddKeyedSingleton<ICache, DefaultCache>(KeyedService.AnyKey);

var provider = services.BuildServiceProvider();

var premium = provider.GetRequiredKeyedService<ICache>("premium");
Console.WriteLine(premium.GetType().Name);  // "PremiumCache"

var basic = provider.GetRequiredKeyedService<ICache>("basic");
Console.WriteLine(basic.GetType().Name);    // "DefaultCache" (fallback)

var other = provider.GetRequiredKeyedService<ICache>("anything");
Console.WriteLine(other.GetType().Name);    // "DefaultCache" (fallback)

La chiave "premium" ha una registrazione dedicata, quindi il container restituisce PremiumCache. Le chiavi "basic" e "anything" non hanno registrazioni esplicite, quindi il container usa il fallback AnyKey e restituisce DefaultCache.

La registrazione con AnyKey supporta anche una factory che riceve la chiave richiesta come secondo parametro. Questo permette di creare istanze personalizzate in base alla chiave, senza dover registrare ogni variante singolarmente:

services.AddKeyedSingleton<ICache>(KeyedService.AnyKey, (sp, key) =>
{
    return new DefaultCache(key?.ToString() ?? "unknown");
});

Pitfall: Keyed e Non-Keyed sono registrazioni separate

Un aspetto che sorprende molti sviluppatori è che le registrazioni keyed e non-keyed per la stessa interfaccia vivono in due mondi completamente separati. Registrare una versione keyed non ha alcun effetto sulla risoluzione non-keyed, e viceversa. Non si sovrascrivono e non interagiscono in alcun modo:

services.AddSingleton<ICache, GlobalCache>();              // non-keyed
services.AddKeyedSingleton<ICache, RedisCache>("redis");   // keyed

var nonKeyed = provider.GetRequiredService<ICache>();
Console.WriteLine(nonKeyed.GetType().Name);                // "GlobalCache"

var keyed = provider.GetRequiredKeyedService<ICache>("redis");
Console.WriteLine(keyed.GetType().Name);                   // "RedisCache"

Questo comportamento è by design, ma va tenuto presente quando si progetta la struttura delle registrazioni. Se un servizio non specifica [FromKeyedServices], riceve sempre la registrazione non-keyed — anche se esistono registrazioni keyed per la stessa interfaccia.

Pitfall: typo nella chiave con AnyKey fallback

AnyKey è comodo ma introduce un rischio che vale la pena conoscere: se si sbaglia a scrivere una chiave, il fallback restituisce l’implementazione di default senza segnalare l’errore. Il risultato è un bug silenzioso.

services.AddKeyedSingleton<ICache, PremiumCache>("premium");
services.AddKeyedSingleton<ICache, DefaultCache>(KeyedService.AnyKey);

// Typo: "premiun" invece di "premium"
var cache = provider.GetRequiredKeyedService<ICache>("premiun");
Console.WriteLine(cache.GetType().Name); // "DefaultCache" — non "PremiumCache"

Il codice funziona, non lancia eccezioni, e restituisce un servizio. Ma è il servizio sbagliato. Senza AnyKey, lo stesso typo avrebbe lanciato un’InvalidOperationException — il che è preferibile, perché il problema è visibile e viene intercettato subito.

Come mitigare

La soluzione è usare costanti o enum per le chiavi, evitando stringhe sparse nel codice:

public static class CacheKeys
{
    public const string Redis = "redis";
    public const string Memory = "memory";
    public const string Premium = "premium";
}

services.AddKeyedSingleton<ICache, RedisCache>(CacheKeys.Redis);
services.AddKeyedSingleton<ICache, MemoryCache>(CacheKeys.Memory);
services.AddKeyedSingleton<ICache, PremiumCache>(CacheKeys.Premium);

public class ProductService(
    [FromKeyedServices(CacheKeys.Redis)] ICache cache)
{ }

In alternativa, sfruttando il fatto che le chiavi possono essere qualsiasi tipo con Equals, si può usare un enum:

public enum CacheType { Redis, Memory, Premium }

services.AddKeyedSingleton<ICache, RedisCache>(CacheType.Redis);
services.AddKeyedSingleton<ICache, MemoryCache>(CacheType.Memory);

In entrambi i casi, un typo diventa un errore di compilazione — eliminando il problema alla radice.

Breaking change in .NET 10: GetKeyedService con AnyKey

In .NET 10 il comportamento di GetKeyedService() e GetKeyedServices() con KeyedService.AnyKey è stato modificato per correggere un’inconsistenza semantica che esisteva fin dall’introduzione dei Keyed Services.

Il problema concettuale

AnyKey è concepito come un wildcard per la registrazione — un meccanismo di fallback che dice al container “usa questa implementazione per qualsiasi chiave non registrata esplicitamente”. Non è una chiave di risoluzione. Ma in .NET 8 e 9, il container lo trattava anche come tale, il che portava a comportamenti confusi: GetKeyedService(KeyedService.AnyKey) restituiva il servizio registrato con AnyKey come se fosse una chiave qualsiasi, e GetKeyedServices(KeyedService.AnyKey) restituiva tutte le registrazioni, incluse quelle AnyKey.

Il cambiamento

In .NET 10, GetKeyedService() (singolare) con AnyKey lancia un’InvalidOperationException:

services.AddKeyedSingleton<ICache, DefaultCache>(KeyedService.AnyKey);
services.AddKeyedSingleton<ICache, PremiumCache>("premium");

var provider = services.BuildServiceProvider();

// .NET 8/9: restituiva DefaultCache
// .NET 10: lancia InvalidOperationException
var service = provider.GetKeyedService<ICache>(KeyedService.AnyKey);
// "Cannot resolve a single service using AnyKey."

GetKeyedServices() (plurale) con AnyKey non restituisce più le registrazioni AnyKey — restituisce solo i servizi registrati con chiavi specifiche:

// .NET 8/9
var all = provider.GetKeyedServices<ICache>(KeyedService.AnyKey);
// [DefaultCache, PremiumCache] — tutte le registrazioni

// .NET 10
var all = provider.GetKeyedServices<ICache>(KeyedService.AnyKey);
// [PremiumCache] — solo le chiavi specifiche, AnyKey esclusa

Il razionale dietro il cambiamento è chiaro: AnyKey è un meccanismo di registrazione, non di risoluzione. Usarlo per risolvere un singolo servizio non aveva senso semanticamente e creava ambiguità.

Come aggiornare il codice

Se il codice usa GetKeyedService(KeyedService.AnyKey) per ottenere il fallback, la migrazione è semplice. Si può registrare il default con una chiave esplicita:

services.AddKeyedSingleton<ICache, DefaultCache>("default");
services.AddKeyedSingleton<ICache, PremiumCache>("premium");

var fallback = provider.GetKeyedService<ICache>("default");

Oppure si può sfruttare la separazione tra keyed e non-keyed, registrando il default come servizio non-keyed:

services.AddSingleton<ICache, DefaultCache>();                  // non-keyed
services.AddKeyedSingleton<ICache, PremiumCache>("premium");    // keyed

var fallback = provider.GetService<ICache>();                    // DefaultCache
var premium = provider.GetKeyedService<ICache>("premium");       // PremiumCache

La seconda opzione è particolarmente pulita: il default è il servizio “normale”, le varianti specifiche sono keyed. Qualsiasi classe che non ha bisogno di una variante specifica riceve il default tramite la classica constructor injection, senza attributi.

Conclusione

I Keyed Services sono un’aggiunta al container DI nativo di .NET che copre uno scenario prima gestibile solo con workaround. I punti da tenere a mente: usare costanti o enum per le chiavi per avere la sicurezza del compilatore, valutare i rischi del fallback AnyKey — in particolare i bug silenziosi da typo — e ricordare che keyed e non-keyed sono registrazioni indipendenti che non si influenzano a vicenda. Per chi sta migrando a .NET 10, verificare che il codice non usi GetKeyedService(KeyedService.AnyKey) per risolvere servizi, perché in .NET 10 lancia un’eccezione.

Con questo articolo chiudiamo la serie sulla Dependency Injection in .NET. I temi che abbiamo coperto — lifetime e le loro regole, anti-pattern dei lifetime, pitfall su registrazione e risoluzione, e Keyed Services — sono le basi per usare la DI in modo consapevole ed evitare i problemi più comuni.

Gli esempi di codice di questa serie sono disponibili nel repository GitHub del talk presentato a Sharp Coding Rome.

Fonti:

• Microsoft Learn — Keyed services
• Microsoft Learn — Breaking change: GetKeyedService with AnyKey in .NET 10
• Microsoft Learn — Dependency injection in ASP.NET Core: Keyed services

Sono pitfall meno discussi rispetto alla Captive Dependency, ma altrettanto frequenti — soprattutto nelle applicazioni che crescono, dove le registrazioni si distribuiscono tra Program.cs, extension method di librerie interne e pacchetti NuGet.

Service Locator

Il Service Locator è un pattern in cui una classe riceve IServiceProvider nel costruttore e lo usa per risolvere le proprie dipendenze internamente, invece di dichiararle esplicitamente.

Il problema

public class NotificationService(IServiceProvider provider)
{
    public void SendNotification(string userId, string message)
    {
        var emailSender = provider.GetRequiredService<IEmailSender>();
        var userRepo = provider.GetRequiredService<IUserRepository>();

        var user = userRepo.GetById(userId);
        emailSender.Send(user.Email, message);
    }
}

Guardando il costruttore, l’unica dipendenza visibile è IServiceProvider. Per sapere che NotificationService ha bisogno di IEmailSender e IUserRepository, bisogna leggere l’implementazione di ogni metodo. In una classe con più metodi, il numero di dipendenze nascoste può crescere senza controllo.

Anche i test diventano più complicati: invece di passare direttamente i mock delle dipendenze, bisogna costruire e configurare un intero IServiceProvider.

// Test con Service Locator: serve mockare IServiceProvider
var mockProvider = new Mock<IServiceProvider>();
mockProvider.Setup(p => p.GetService(typeof(IEmailSender)))
            .Returns(new Mock<IEmailSender>().Object);
mockProvider.Setup(p => p.GetService(typeof(IUserRepository)))
            .Returns(new Mock<IUserRepository>().Object);
// ... e così via per ogni dipendenza nascosta

Le linee guida Microsoft sono esplicite: “Avoid using the service locator pattern. For example, don’t invoke GetService to obtain a service instance when you can use DI instead.”

La soluzione

Dichiarare le dipendenze nel costruttore:

public class NotificationService(
    IEmailSender emailSender,
    IUserRepository userRepo)
{
    public void SendNotification(string userId, string message)
    {
        var user = userRepo.GetById(userId);
        emailSender.Send(user.Email, message);
    }
}

Le dipendenze sono visibili, il costruttore documenta ciò che serve alla classe, e i test sono diretti:

var mockEmail = new Mock<IEmailSender>();
var sut = new NotificationService(
    mockEmail.Object,
    Mock.Of<IUserRepository>());

sut.SendNotification("user1", "Hello");

mockEmail.Verify(e => e.Send(It.IsAny<string>(), "Hello"), Times.Once);

Factory asincrone e deadlock

Il container DI di .NET risolve i servizi in modo sincrono. Non esiste un GetRequiredServiceAsync. Questo significa che le factory passate a AddSingleton, AddScoped e AddTransient devono essere sincrone.

Il problema

services.AddSingleton<IConnection>(sp =>
{
    return CreateConnectionAsync(sp).Result; // blocca il thread
});

async Task<IConnection> CreateConnectionAsync(IServiceProvider sp)
{
    var config = sp.GetRequiredService<IConfiguration>();
    var connection = new SqlConnection(config.GetConnectionString("Default"));
    await connection.OpenAsync();
    return connection;
}

Chiamare .Result su un Task all’interno di una factory DI blocca il thread corrente fino al completamento dell’operazione asincrona. Questo può causare un deadlock per due motivi:

• Se esiste un SynchronizationContext (es. in WPF, WinForms, o Blazor Server), il Task potrebbe aver bisogno di riprendere sullo stesso thread che è bloccato in attesa.
• Se il metodo asincrono chiama a sua volta GetRequiredService sul container, questo può entrare in conflitto con la risoluzione già in corso, che detiene un lock interno.

La documentazione Microsoft classifica questo come un anti-pattern esplicito: “If the factory is asynchronous, and you use Task<TResult>.Result, it will cause a deadlock.” La raccomandazione è: “Keep DI factories fast and synchronous.”

Le soluzioni

1) Lazy async initialization:

public class ConnectionWrapper(IConfiguration config)
{
    private readonly Lazy<Task<IConnection>> _connection = new(async () =>
    {
        var conn = new SqlConnection(config.GetConnectionString("Default"));
        await conn.OpenAsync();
        return conn;
    });

    public Task<IConnection> GetConnectionAsync() => _connection.Value;
}

services.AddSingleton<ConnectionWrapper>();

La factory registrata nel container è sincrona (crea un ConnectionWrapper). L’inizializzazione asincrona avviene alla prima chiamata di GetConnectionAsync(), fuori dal contesto di risoluzione del container.

2) Inizializzazione prima della build:

var builder = Host.CreateApplicationBuilder(args);

var connection = await CreateConnectionAsync(builder.Configuration);
builder.Services.AddSingleton<IConnection>(connection);

L’istanza viene creata in modo asincrono prima di essere registrata. Non c’è nessuna factory — si registra direttamente l’oggetto già inizializzato.

3) IHostedService per il warm-up:

public class ConnectionInitializer(ConnectionWrapper wrapper) : IHostedService
{
    public async Task StartAsync(CancellationToken ct)
    {
        await wrapper.GetConnectionAsync();
    }

    public Task StopAsync(CancellationToken ct) => Task.CompletedTask;
}

Combinato con la soluzione 1, l’IHostedService forza l’inizializzazione della connessione all’avvio dell’applicazione, prima che arrivi la prima richiesta.

Registrazioni multiple: l’ultima vince

Quando si registra la stessa interfaccia più volte nel container, il comportamento è diverso a seconda di come si risolve il servizio.

Il problema

services.AddSingleton<IMessageWriter, ConsoleMessageWriter>();
services.AddSingleton<IMessageWriter, LoggingMessageWriter>();
services.AddSingleton<IMessageWriter, FileMessageWriter>();

var provider = services.BuildServiceProvider();

// Risoluzione singola: l'ultimo registrato
var writer = provider.GetRequiredService<IMessageWriter>();
Console.WriteLine(writer.GetType().Name); // "FileMessageWriter"

// Risoluzione multipla: tutti, in ordine di registrazione
var all = provider.GetRequiredService<IEnumerable<IMessageWriter>>();
// [ConsoleMessageWriter, LoggingMessageWriter, FileMessageWriter]

Se si risolve un singolo IMessageWriter, il container restituisce l’ultima implementazione registrata. Le registrazioni precedenti non vengono sovrascritte — restano disponibili tramite IEnumerable<IMessageWriter> — ma per la risoluzione singola, l’ultima vince.

Questo è il comportamento documentato: “The second call to AddSingleton overrides the previous one when resolved as IMyDependency and adds to the previous one when multiple services are resolved via IEnumerable<IMyDependency>. Services appear in the order they were registered when resolved via IEnumerable<{SERVICE}>.”

Il container non lancia alcun avviso. Se una extension method di una libreria registra la propria implementazione di IMessageWriter dopo la nostra, il nostro servizio viene sostituito senza alcuna segnalazione. Questo succede facilmente quando le registrazioni sono distribuite tra più file o pacchetti.

Le soluzioni

TryAdd — registra solo se il service type non è già presente:

using Microsoft.Extensions.DependencyInjection.Extensions;

services.AddSingleton<IMessageWriter, ConsoleMessageWriter>();
services.TryAddSingleton<IMessageWriter, LoggingMessageWriter>();
// LoggingMessageWriter viene ignorato: IMessageWriter è già registrato

var writer = provider.GetRequiredService<IMessageWriter>();
Console.WriteLine(writer.GetType().Name); // "ConsoleMessageWriter"

Con TryAdd, la prima registrazione vince. Le successive per lo stesso service type vengono ignorate.

TryAddEnumerable — evita duplicati nelle registrazioni multiple:

services.TryAddEnumerable(
    ServiceDescriptor.Singleton<IMessageWriter, ConsoleMessageWriter>());
services.TryAddEnumerable(
    ServiceDescriptor.Singleton<IMessageWriter, LoggingMessageWriter>());
services.TryAddEnumerable(
    ServiceDescriptor.Singleton<IMessageWriter, ConsoleMessageWriter>());
// ^ Ignorata: la coppia (IMessageWriter, ConsoleMessageWriter) è già presente

var all = provider.GetRequiredService<IEnumerable<IMessageWriter>>();
// [ConsoleMessageWriter, LoggingMessageWriter] — senza duplicati

TryAddEnumerable controlla sia il service type che l’implementation type: aggiunge solo se quella specifica coppia non è già registrata.

Riepilogo:

Add<T, Impl>()        → aggiunge sempre (l'ultimo vince per singolo, tutti per IEnumerable)
TryAdd<T, Impl>()     → aggiunge solo se T non è già registrato
TryAddEnumerable(...)  → aggiunge solo se la coppia (T, Impl) non è già presente

Conclusione

I tre problemi di questo articolo hanno in comune il fatto di manifestarsi in silenzio. Il Service Locator nasconde le dipendenze e non produce errori. Una factory asincrona con .Result può funzionare in assenza di SynchronizationContext e poi bloccarsi in un contesto diverso. E una registrazione sovrascritta passa inosservata finché il servizio non si comporta in modo inatteso.

Le contromisure: constructor injection esplicita, factory sincrone (con lazy initialization o IHostedService per i casi asincroni), e TryAdd/TryAddEnumerable per registrazioni sicure.

Nel prossimo articolo chiudiamo la serie con i Keyed Services: registrazione con chiave, AnyKey, e la breaking change in .NET 10.

Fonti:

• Microsoft Learn — Dependency injection guidelines
• Microsoft Learn — Async DI factories can cause deadlocks
• Microsoft Learn — Service registration methods

I problemi legati ai lifetime sono tra i più insidiosi nella Dependency Injection, perché spesso non si manifestano durante lo sviluppo o nei test. Un DbContext catturato in un Singleton, ad esempio, può funzionare per ore prima di mostrare comportamenti anomali. Un memory leak da Transient Disposable cresce lentamente e diventa visibile solo sotto carico. E un servizio Scoped che diventa Singleton passa inosservato finché due request non si trovano a condividere stato che dovrebbe essere isolato.

Vediamo questi tre scenari nel dettaglio.

Captive Dependency

Il termine Captive Dependency è stato coniato da Mark Seemann e indica una situazione in cui un servizio con lifetime lungo (es. Singleton) cattura un servizio con lifetime più breve (es. Scoped). Il servizio catturato sopravvive oltre il suo ciclo di vita previsto.

Il problema

var services = new ServiceCollection();
services.AddSingleton<OrderService>();
services.AddScoped<FakeDbContext>();

public class OrderService(FakeDbContext db)
{
    public void CreateOrder(Order order)
    {
        db.Orders.Add(order);
        db.SaveChanges();
    }
}

OrderService è Singleton, quindi viene creato una sola volta. Il FakeDbContext iniettato al momento della creazione resta lo stesso per tutta la vita dell’applicazione, anche se era registrato come Scoped. Le request successive continuano a usare la stessa istanza di DbContext — con tutto lo stato accumulato dalle operazioni precedenti.

Il risultato: tracking di entità inconsistente, dati stale, possibili eccezioni.

Le soluzioni

1) Usare IServiceScopeFactory per creare scope on-demand:

public class OrderService(IServiceScopeFactory scopeFactory)
{
    public void CreateOrder(Order order)
    {
        using var scope = scopeFactory.CreateScope();
        var db = scope.ServiceProvider.GetRequiredService<FakeDbContext>();
        db.Orders.Add(order);
        db.SaveChanges();
    }
}

Ogni chiamata a CreateOrder crea un nuovo scope con la propria istanza di DbContext, che viene correttamente disposta alla fine del blocco using. IServiceScopeFactory è sempre registrato come Singleton dal container, quindi può essere iniettato senza problemi in un servizio Singleton.

2) Allineare i lifetime:

services.AddScoped<OrderService>();
services.AddScoped<FakeDbContext>();

Se OrderService non ha motivo di essere Singleton, la soluzione più semplice è registrarlo come Scoped. Entrambi i servizi vivranno per la durata della request.

3) Abilitare ValidateScopes:

var provider = services.BuildServiceProvider(new ServiceProviderOptions
{
    ValidateScopes = true,
    ValidateOnBuild = true
});

Con ValidateOnBuild = true, il problema viene rilevato al momento della build del provider. Con ValidateScopes = true senza ValidateOnBuild, l’eccezione viene lanciata alla prima risoluzione di OrderService:

Cannot consume scoped service 'FakeDbContext' from singleton 'OrderService'.

Transient Disposable catturati dal container

Quando un servizio Transient implementa IDisposable, il container DI mantiene un riferimento a ogni istanza creata per poterla disporre quando lo scope (o il container stesso) viene distrutto. Se queste istanze vengono risolte dal root provider (senza scope), si accumulano in memoria fino allo shutdown dell’applicazione.

Il problema

public class ExpensiveResource : IDisposable
{
    private readonly byte[] _buffer = new byte[1024 * 1024]; // 1MB

    public void DoWork() => Console.WriteLine("Working...");

    public void Dispose()
    {
        Console.WriteLine($"{nameof(ExpensiveResource)} disposed");
    }
}

services.AddTransient<ExpensiveResource>();

var provider = services.BuildServiceProvider();

for (int i = 0; i < 1000; i++)
{
    var resource = provider.GetRequiredService<ExpensiveResource>();
    resource.DoWork();
    // Ogni istanza viene trattenuta dal container
}
// 1000 istanze × 1MB = ~1GB di memoria non rilasciata
// Il Dispose avviene solo quando il provider viene disposto (shutdown dell'app)

Il container tiene traccia di tutte le istanze Transient IDisposable che crea, perché è sua responsabilità chiamare Dispose() su di esse. Se non c’è uno scope che delimita il ciclo di vita, le istanze restano in memoria fino alla fine dell’applicazione.

Le soluzioni

1) Usare uno scope per ogni unità di lavoro:

for (int i = 0; i < 1000; i++)
{
    using var scope = provider.CreateScope();
    var resource = scope.ServiceProvider.GetRequiredService<ExpensiveResource>();
    resource.DoWork();
} // Alla fine di ogni scope, le istanze transient vengono disposte

2) Factory pattern per la gestione manuale del ciclo di vita:

services.AddSingleton<Func<ExpensiveResource>>(() => new ExpensiveResource());

public class MyService(Func<ExpensiveResource> resourceFactory)
{
    public void Process()
    {
        using var resource = resourceFactory();
        resource.DoWork();
    }
}

Con il factory pattern, l’istanza non è gestita dal container — siamo noi a crearla e a chiamare Dispose(). Il container non trattiene alcun riferimento.

Le linee guida ufficiali di Microsoft su questo punto sono chiare: evitare di registrare servizi IDisposable come Transient. Se necessario, usare il factory pattern.

Servizio Scoped risolto come Singleton

Se un servizio Scoped viene risolto dal root IServiceProvider — cioè senza creare uno scope — il suo lifetime viene di fatto promosso a Singleton. Il servizio viene creato una sola volta e riutilizzato per tutte le richieste successive.

Il problema

public class RequestContext
{
    public Guid RequestId { get; } = Guid.NewGuid();
    public string? UserName { get; private set; }
    public void SetUser(string userName) => UserName = userName;
}

services.AddScoped<RequestContext>();

var provider = services.BuildServiceProvider();

// Risoluzione dal root provider, senza scope
var request1 = provider.GetRequiredService<RequestContext>();
request1.SetUser("alice");

var request2 = provider.GetRequiredService<RequestContext>();
request2.SetUser("bob");

Console.WriteLine(ReferenceEquals(request1, request2)); // true
Console.WriteLine(request1.UserName); // bob
// request1 e request2 sono la stessa istanza:
// stato condiviso accidentalmente tra "request" diverse

In ASP.NET Core questo problema non si presenta per le request HTTP, perché il framework crea automaticamente uno scope per ogni request. Il rischio esiste nei background service, nelle console app e in qualsiasi contesto dove lo scope non viene creato automaticamente.

La soluzione

Creare sempre uno scope esplicito quando si risolvono servizi Scoped fuori da ASP.NET Core:

var provider = services.BuildServiceProvider();

for (int i = 1; i <= 3; i++)
{
    using var scope = provider.CreateScope();
    var request = scope.ServiceProvider.GetRequiredService<RequestContext>();
    request.SetUser($"user-{i}");
    Console.WriteLine($"Scope {i}: {request.RequestId} - {request.UserName}");
}
// Ogni scope ha la propria istanza di RequestContext

Anche in questo caso, ValidateScopes rileva il problema. Se abilitato, risolvere un servizio Scoped dal root provider lancia un’eccezione:

Cannot resolve scoped service 'RequestContext' from root provider.

Conclusione

I tre anti-pattern di questo articolo hanno un denominatore comune: un disallineamento tra il lifetime dichiarato e quello effettivo del servizio. La Captive Dependency cattura un servizio Scoped in un Singleton, i Transient Disposable si accumulano senza essere rilasciati, e un servizio Scoped risolto dal root provider diventa un Singleton accidentale.

Le contromisure sono semplici: usare IServiceScopeFactory quando un Singleton ha bisogno di servizi Scoped, gestire esplicitamente gli scope per i Transient Disposable, e abilitare ValidateScopes e ValidateOnBuild per intercettare questi problemi prima che raggiungano la produzione.

Nel prossimo articolo vedremo il Service Locator pattern, i deadlock nelle factory asincrone e il comportamento delle registrazioni multiple.

Fonti:

• Microsoft Learn — Dependency injection guidelines: anti-patterns
• Microsoft Learn — IDisposable guidance for transient and shared instances
• Mark Seemann — Captive Dependency