C# Academy · Leçon

Configurer Asp.Versioning

Configurez le versionnement dans ASP.NET Core.

Configurer Asp.Versioning est une leçon C# Academy gratuite sur CoddyKit. Ceci est la leçon 2 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage C# Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours C# Academy comprend 4 leçons au total.

Le package Asp.Versioning

Le versionnage des API ASP.NET Core repose sur les packages Asp.Versioning, maintenus par la communauté (successeurs de Microsoft.AspNetCore.Mvc.Versioning).

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

AddApiVersioning

Enregistrez le versionnage avec AddApiVersioning. Les options contrôlent la version par défaut et la manière de gérer les versions manquantes.

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

ReportApiVersions

ReportApiVersions = true ajoute les en-têtes de réponse api-supported-versions et api-deprecated-versions, afin que les clients puissent découvrir les versions disponibles.

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

Choisir le lecteur de version

Le ApiVersionReader détermine l’emplacement depuis lequel la version est lue. UrlSegmentApiVersionReader la lit dans le chemin de la route.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Combiner les lecteurs

Acceptez la version depuis plusieurs emplacements à la fois avec ApiVersionReader.Combine.

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

Ajouter l’explorateur d’API

Enchaînez AddApiExplorer afin que la gestion des versions s’intègre à OpenAPI. La chaîne de format contrôle l’apparence des noms de groupes de versions.

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

Gérer les versions d’un contrôleur

Décorez un contrôleur avec [ApiVersion] et placez l’espace réservé à la version dans le modèle de route.

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

Une deuxième version

Un contrôleur distinct sert v2 avec le même modèle de route. Le segment {version:apiVersion} achemine les requêtes vers le contrôleur approprié.

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

Plusieurs versions sur un contrôleur

Un seul contrôleur peut servir plusieurs versions, en associant des actions individuelles avec [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");
}

Marquer une version comme obsolète

Marquez une version comme obsolète pour annoncer sa fin de vie tout en la laissant fonctionnelle.

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

Gérer les versions des API minimales

Les API minimales utilisent un ensemble de versions créé avec NewApiVersionSet, puis associent des versions à chaque point de terminaison.

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

Vérification rapide

Vérifiez à quoi sert AddApiExplorer.

Récapitulatif

Vous avez configuré Asp.Versioning :

AddApiVersioning définit la version par défaut et la publication des informations de version.
ApiVersionReader.Combine lit les versions dans l’URL, l’en-tête ou la chaîne de requête.
[ApiVersion] et {version:apiVersion} acheminent les requêtes ; [MapToApiVersion] cible les actions.
Les API minimales utilisent un ensemble de versions.

Ensuite : générer des documents OpenAPI.

Questions Fréquemment Posées

La leçon « Configurer Asp.Versioning » est-elle gratuite ?

Oui — le texte complet de « Configurer Asp.Versioning » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours C# Academy, passe à CoddyKit PRO. Le cours C# Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « Configurer Asp.Versioning » ?

Configurez le versionnement dans ASP.NET Core. Tu pratiques C# Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer C# Academy ?

Aucune expérience préalable n'est requise. C# Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 2 sur 4.

Combien de temps prend la leçon « Configurer Asp.Versioning » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon C# Academy ?

Oui. Chaque leçon C# Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à C# Academy