Quando creiamo un progetto destinato a durare per tempo, avere un corretto versioning degli endpoint esposti è assolutamente cruciale per far sì che anche i client non aggiornati siano in grado di continuare a funzionare, senza il rischio di introdurre breaking change.
Una libreria che rende molto semplice la soluzione di questo problema è Asp.Versioning (https://github.com/dotnet/aspnet-api-versioning) pubblicata e manutenuta da .NET Foundation.
Per sfruttarla in un nostro progetto, non dobbiamo far altro che aggiungere il corrisponente package
dotnet add package Asp.Versioning.Http
e poi registrare il corrispondente servizio nel nostro IoC container:
public static void Main(string[] args) { var builder = WebApplication.CreateBuilder(args); builder.Services.AddApiVersioning(); // altro codice qui ...
A questo punto, possiamo finalmente iniziare a decorare tutti i nostri endpoint con la versione corrispondente:
var myVersionedApi = app.NewVersionedApi(); myVersionedApi.MapGet("/weatherforecast", (HttpContext httpContext) => { var forecast = Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), TemperatureC = Random.Shared.Next(-20, 55), Summary = summaries[Random.Shared.Next(summaries.Length)] }) .ToArray(); return forecast; }).HasApiVersion(1.0); myVersionedApi.MapGet("/weatherforecast", (HttpContext httpContext) => { var forecast = Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), TemperatureC = Random.Shared.Next(-20, 55), Summary = "Version 2 is always Hot!" }) .ToArray(); return forecast; }).HasApiVersion(2.0);
Nello script in alto, la differenza sostanziale che possiamo notare è che invece di registrare gli endpoint direttamente sull'app builder, abbiamo come primo passo creato una Versioned API invocando l'extension method NewVersionedApi.
A questo punto, non dobbiamo far altro che decorare i vari endpoint tramite HasApiVersion per specificarne il numero di versione.
Se proviamo a eseguire l'applicazione, in questa modalità di default, potremo cambiare il numero di versione tramite il parametro api-version in query string. La libreria ritornerà automaticamente un errore 400 (Bad Request) nel caso in cui il numero di versione sia non esistente o non supportato.
Se abbiamo introdotto il versioning "a posteriori", alcuni client legacy potrebbero non esserne a conoscenza, e in questi casi è utile indirizzarli per default alla versione 1.0:
builder.Services.AddApiVersioning(config => { config.AssumeDefaultVersionWhenUnspecified = true; config.DefaultApiVersion = new ApiVersion(1, 0); });
Asp.Versioning è una libreria estremamente versatile. Nel corso dei prossimi script daremo un'occhiata più approfondita alle sue funzionalità, partendo da come utilizzarla anche con i controller.
Commenti
Per inserire un commento, devi avere un account.
Fai il login e torna a questa pagina, oppure registrati alla nostra community.
Approfondimenti
Eseguire operazioni sui blob con Azure Storage Actions
Utilizzare Azure AI Studio per testare i modelli AI
Evitare la script injection nelle GitHub Actions
Gestire liste di tipi semplici con Entity Framework Core
Eseguire i worklow di GitHub su runner potenziati
Creazione di plugin per Tailwind CSS: espandere le Funzionalità del Framework
Utilizzare Copilot con Azure Cosmos DB
gRPC con .NET
Miglioramenti nelle performance di Angular 16
Installare le Web App site extension tramite una pipeline di Azure DevOps
Personalizzare l'errore del rate limiting middleware in ASP.NET Core
Utilizzare gRPC su App Service di Azure
I più letti di oggi
- anche domani dalle 17:30 seguite con noi live #build15 https://aspit.co/build15
- Webcast 'AJAX & ATLAS Overview'
- a #igds il 25 e 26/10 a Milano puoi sviluppare un gioco per #wp8 con @AppCampus. in palio 70.000 Euro: https://aspit.co/apa
- WinJS in Windows Phone 8.1
- la RC di #vs13 è compatibile con #win81 RTM, non con la Preview. l'annuncio ufficiale è su https://aspit.co/any
- Ancora un bug: esce Mono 0.23
- SSL Certificates for everyone on Azure
- Mostrare una MessageBox con un custom control
- disponibile la preview 1 ci #dotnetcore 2.1, #aspnetcore, #efcore. performance, novità e migliorie su https://aspit.co/bmf
- si continua a #netconfit con 'developing modern web apps with #aspnetcore', con il nostro @dbochicchiohttps://aspit.co/netconf-18