C# Academy · Aula

Configurando Asp.Versioning

Configure o versionamento no ASP.NET Core.

Configurando Asp.Versioning é uma aula grátis de C# Academy no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de C# Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de C# Academy inclui 4 aulas no total.

O pacote Asp.Versioning

O versionamento de APIs do ASP.NET Core está nos pacotes Asp.Versioning, mantidos pela comunidade (sucessores de Microsoft.AspNetCore.Mvc.Versioning).

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

AddApiVersioning

Registre o versionamento com AddApiVersioning. As opções controlam a versão padrão e a forma como versões ausentes são tratadas.

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

ReportApiVersions

ReportApiVersions = true adiciona os cabeçalhos de resposta api-supported-versions e api-deprecated-versions, para que os clientes possam descobrir o que está disponível.

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

Escolhendo o leitor de versão

O ApiVersionReader decide de onde a versão será lida. UrlSegmentApiVersionReader a lê do caminho da rota.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Combinando leitores

Aceite a versão de vários locais ao mesmo tempo com ApiVersionReader.Combine.

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

Adicionando o API Explorer

Encadeie AddApiExplorer para que o versionamento seja integrado ao OpenAPI. A cadeia de formato controla a aparência dos nomes dos grupos de versões.

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

Versionando um controlador

Decore um controlador com [ApiVersion] e coloque o marcador de versão no modelo de rota.

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

Uma segunda versão

Um controlador separado disponibiliza a v2 usando o mesmo modelo de rota. O segmento {version:apiVersion} encaminha as solicitações para o controlador correto.

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

Várias versões em um controlador

Um único controlador pode disponibilizar várias versões, mapeando ações individuais com [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");
}

Descontinuando uma versão

Marque uma versão como descontinuada para informar que ela será encerrada, mantendo-a funcional.

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

Versionando APIs mínimas

As APIs mínimas usam um conjunto de versões criado com NewApiVersionSet e, em seguida, associam versões a cada ponto de extremidade.

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ção rápida

Confirme para que serve AddApiExplorer.

Recapitulação

Você configurou o Asp.Versioning:

AddApiVersioning define a versão padrão e a geração de relatórios.
ApiVersionReader.Combine lê as versões da URL, do cabeçalho ou da cadeia de consulta.
[ApiVersion] e {version:apiVersion} encaminham as solicitações; [MapToApiVersion] direciona as ações.
As APIs mínimas usam um conjunto de versões.

Próximo tópico: gerar documentos OpenAPI.

Perguntas Frequentes

A aula “Configurando Asp.Versioning” é grátis?

Sim — o texto completo de “Configurando Asp.Versioning” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de C# Academy, atualize para CoddyKit PRO. O curso de C# Academy inclui 4 aulas no total.

O que vou aprender em “Configurando Asp.Versioning”?

Configure o versionamento no ASP.NET Core. Você pratica C# Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar C# Academy?

Nenhuma experiência prévia é necessária. C# Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.

Quanto tempo leva a aula “Configurando Asp.Versioning”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de C# Academy?

Sim. Cada aula de C# Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para C# Academy