C# Academy · Урок

Настройка Asp.Versioning

Настройте версионирование в ASP.NET Core.

«Настройка Asp.Versioning» — бесплатный урок C# Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения C# Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс C# Academy содержит 4 уроков всего.

Пакет Asp.Versioning

Версионирование API в ASP.NET Core реализовано в пакетах Asp.Versioning, которые поддерживаются сообществом и являются преемниками Microsoft.AspNetCore.Mvc.Versioning.

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

AddApiVersioning

Зарегистрируйте версионирование с помощью AddApiVersioning. Параметры управляют версией по умолчанию и обработкой отсутствующих версий.

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

ReportApiVersions

ReportApiVersions = true добавляет в ответы заголовки api-supported-versions и api-deprecated-versions, чтобы клиенты могли узнать, какие версии доступны.

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

Выбор средства чтения версии

ApiVersionReader определяет, откуда считывается версия. UrlSegmentApiVersionReader считывает её из пути маршрута.

options.ApiVersionReader = new UrlSegmentApiVersionReader();

Объединение средств чтения

Принимайте версию сразу из нескольких источников с помощью ApiVersionReader.Combine.

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

Добавление обозревателя API

Свяжите AddApiExplorer с версионированием, чтобы оно интегрировалось с OpenAPI. Строка формата управляет тем, как выглядят имена групп версий.

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

Версионирование контроллера

Пометьте контроллер атрибутом [ApiVersion] и поместите заполнитель версии в шаблон маршрута.

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

Вторая версия

Отдельный контроллер обслуживает v2 по тому же шаблону маршрута. Сегмент {version:apiVersion} направляет запросы к нужному контроллеру.

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

Несколько версий одного контроллера

Один контроллер может обслуживать несколько версий, сопоставляя отдельные действия с помощью [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");
}

Пометка версии как устаревшей

Пометьте версию как устаревшую, чтобы сообщить о прекращении её поддержки, сохранив её работоспособность.

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

Версионирование минимальных API

Минимальные API используют набор версий, созданный с помощью NewApiVersionSet, а затем назначают версии каждой конечной точке.

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

Быстрая проверка

Проверьте, для чего предназначен AddApiExplorer.

Итоги

Вы настроили Asp.Versioning:

AddApiVersioning задаёт версию по умолчанию и публикацию сведений о версиях.
ApiVersionReader.Combine считывает версии из URL, заголовка или строки запроса.
[ApiVersion] и {version:apiVersion} направляют запросы; [MapToApiVersion] выбирает действия.
Минимальные API используют набор версий.

Далее: генерация документов OpenAPI.

Часто задаваемые вопросы

Урок «Настройка Asp.Versioning» бесплатный?

Да — полный текст урока «Настройка Asp.Versioning» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс C# Academy, подпишись на CoddyKit PRO. Курс C# Academy содержит 4 уроков всего.

Чему я научусь в уроке «Настройка Asp.Versioning»?

Настройте версионирование в ASP.NET Core. Ты практикуешь C# Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать C# Academy?

Предыдущий опыт не требуется. C# Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 2 из 4.

Сколько времени занимает урок «Настройка Asp.Versioning»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке C# Academy?

Да. Каждый урок C# Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к C# Academy