C# Academy · Lezione

Configurazione di Asp.Versioning

Configuri il versionamento in ASP.NET Core.

Configurazione di Asp.Versioning è una lezione C# Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento C# Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso C# Academy include 4 lezioni in totale.

Il pacchetto Asp.Versioning

Il versioning delle API di ASP.NET Core è fornito dai pacchetti Asp.Versioning gestiti dalla community (successori di Microsoft.AspNetCore.Mvc.Versioning).

dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorer

AddApiVersioning

Registri il versioning con AddApiVersioning. Le opzioni controllano la versione predefinita e la gestione delle versioni mancanti.

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

ReportApiVersions

ReportApiVersions = true aggiunge gli header di risposta api-supported-versions e api-deprecated-versions, consentendo ai client di scoprire quali versioni sono disponibili.

// Response headers:
// api-supported-versions: 1.0, 2.0
// api-deprecated-versions: 1.0

Scegliere il lettore della versione

ApiVersionReader stabilisce da dove viene letta la versione. UrlSegmentApiVersionReader la legge dal percorso della route.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Combinare i lettori

Accetti la versione da più origini contemporaneamente con ApiVersionReader.Combine.

options.ApiVersionReader = ApiVersionReader.Combine(
    new UrlSegmentApiVersionReader(),
    new HeaderApiVersionReader("X-Api-Version"),
    new QueryStringApiVersionReader("api-version"));

Aggiunta di API Explorer

Colleghi AddApiExplorer per integrare il versionamento con OpenAPI. La stringa di formato controlla l'aspetto dei nomi dei gruppi di versione.

builder.Services
    .AddApiVersioning(options => { /* ... */ })
    .AddApiExplorer(options =>
    {
        options.GroupNameFormat = "'v'VVV";
        options.SubstituteApiVersionInUrl = true;
    });

Versionamento di un controller

Decori un controller con [ApiVersion] e inserisca il segnaposto della versione nel modello di route.

[ApiVersion(1.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() => Ok(new { version = "1.0" });
}

Una seconda versione

Un controller separato gestisce la v2 usando lo stesso modello di route. Il segmento {version:apiVersion} indirizza le richieste al controller corretto.

[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get() =>
        Ok(new { version = "2.0", extra = true });
}

Più versioni in un controller

Un singolo controller può gestire più versioni, associando le singole azioni con [MapToApiVersion].

[ApiVersion(1.0)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase
{
    [HttpGet, MapToApiVersion(1.0)]
    public IActionResult GetV1() => Ok("v1");

    [HttpGet, MapToApiVersion(2.0)]
    public IActionResult GetV2() => Ok("v2");
}

Deprecazione di una versione

Contrassegni una versione come deprecata per annunciarne il ritiro, mantenendola comunque funzionante.

[ApiVersion(1.0, Deprecated = true)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase { }

Versionamento delle Minimal API

Le Minimal API usano un set di versioni creato con NewApiVersionSet, quindi associano le versioni ai singoli endpoint.

var versionSet = app.NewApiVersionSet()
    .HasApiVersion(new ApiVersion(1, 0))
    .HasApiVersion(new ApiVersion(2, 0))
    .Build();

app.MapGet("/api/v{version:apiVersion}/ping", () => "pong")
   .WithApiVersionSet(versionSet)
   .MapToApiVersion(2.0);

Verifica rapida

Verifichi a cosa serve AddApiExplorer.

Riepilogo

Ha configurato Asp.Versioning:

AddApiVersioning imposta la versione predefinita e la generazione dei report.
ApiVersionReader.Combine legge le versioni dall'URL, dall'header o dalla query string.
[ApiVersion] e {version:apiVersion} indirizzano le richieste; [MapToApiVersion] seleziona le azioni.
Le Minimal API usano un set di versioni.

Prossimo argomento: generazione dei documenti OpenAPI.

Domande Frequenti

La lezione «Configurazione di Asp.Versioning» è gratuita?

Sì — il testo completo di «Configurazione di Asp.Versioning» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso C# Academy, passa a CoddyKit PRO. Il corso C# Academy include 4 lezioni in totale.

Cosa imparerò in «Configurazione di Asp.Versioning»?

Configuri il versionamento in ASP.NET Core. Eserciti C# Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare C# Academy?

Non è richiesta alcuna esperienza precedente. C# Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Configurazione di Asp.Versioning»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione C# Academy?

Sì. Ogni lezione C# Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a C# Academy