C# Academy · Lección

Configuración de Asp.Versioning

Configure el versionado en ASP.NET Core.

Configuración de Asp.Versioning es una lección gratuita de C# Academy en CoddyKit. Esta es la lección 2 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de C# Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de C# Academy incluye 4 lecciones en total.

El paquete Asp.Versioning

El versionado de API de ASP.NET Core se encuentra en los paquetes Asp.Versioning, mantenidos por la comunidad (sucesores de Microsoft.AspNetCore.Mvc.Versioning).

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

AddApiVersioning

Registre el versionado mediante AddApiVersioning. Las opciones controlan la versión predeterminada y cómo se gestionan las versiones que faltan.

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

ReportApiVersions

ReportApiVersions = true añade los encabezados de respuesta api-supported-versions y api-deprecated-versions, para que los clientes puedan descubrir qué opciones están disponibles.

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

Elegir el lector de versiones

ApiVersionReader determina de dónde se lee la versión. UrlSegmentApiVersionReader la lee de la ruta.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Combinar lectores

Acepte la versión desde varios lugares a la vez mediante ApiVersionReader.Combine.

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

Adición de API Explorer

Encadene AddApiExplorer para integrar el versionado con OpenAPI. La cadena de formato controla el aspecto de los nombres de los grupos de versiones.

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

Versionado de un controlador

Decore un controlador con [ApiVersion] y coloque el marcador de versión en la plantilla de ruta.

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

Una segunda versión

Un controlador independiente sirve la v2 con la misma plantilla de ruta. El segmento {version:apiVersion} dirige las solicitudes al controlador correcto.

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

Varias versiones en un controlador

Un solo controlador puede servir varias versiones, asignando acciones individuales 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");
}

Retirada de una versión

Marque una versión como obsoleta para anunciar su fecha de retirada, manteniéndola funcional.

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

Versionado de Minimal APIs

Minimal APIs utilizan un conjunto de versiones creado con NewApiVersionSet y, después, asocian versiones a cada 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);

Comprobación rápida

Confirme para qué sirve AddApiExplorer.

Resumen

Ha configurado Asp.Versioning:

AddApiVersioning establece la versión predeterminada y la información de versiones.
ApiVersionReader.Combine lee las versiones de la URL, de un encabezado o de una cadena de consulta.
[ApiVersion] y {version:apiVersion} dirigen las solicitudes; [MapToApiVersion] selecciona las acciones.
Minimal APIs utilizan un conjunto de versiones.

Siguiente: generar documentos de OpenAPI.

Preguntas frecuentes

¿La lección «Configuración de Asp.Versioning» es gratis?

Sí — el texto completo de «Configuración de Asp.Versioning» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de C# Academy, actualiza a CoddyKit PRO. El curso de C# Academy incluye 4 lecciones en total.

¿Qué aprenderé en «Configuración de Asp.Versioning»?

Configure el versionado en ASP.NET Core. Practicas C# Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar C# Academy?

No se requiere experiencia previa. C# Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 2 de 4.

¿Cuánto tiempo toma la lección «Configuración de Asp.Versioning»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de C# Academy?

Sí. Cada lección de C# Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

← Volver a C# Academy