Как создавать версии минимальных API в ASP.NET Core 6

ASP.NET Core 6 представляет упрощенную модель хостинга, которая позволяет нам создавать облегченные API с минимальными зависимостями. В предыдущей статье мы обсудили начало работы с минимальными API, использование ведения журналов и внедрения зависимостей с минимальными API, а также тестирование минимальных API. В этой статье мы рассмотрим, как можно реализовать управление версиями для наших минимальных конечных точек API.

Мы проиллюстрируем, как можно создавать версии минимальных API в ASP.NET 6 Core, выполнив следующую последовательность из шести шагов:

1. Создайте проект минимального API ASP.NET 6 Core в Visual Studio 2022.
2. Установите необходимые пакеты NuGet.
3. Добавьте поддержку версий API в наш проект
4. Создать набор версий
5. Создайте конечные точки API и свяжите набор версий.
6. Выполнение конечных точек API в Postman

Для работы с примерами кода, представленными в этой статье, в вашей системе должна быть установлена ​​Visual Studio 2022. Если у вас еще нет копии, вы можете скачать Visual Studio 2022 здесь.

Создайте минимальный проект веб-API ASP.NET Core 6 в Visual Studio 2022.

Прежде всего давайте создадим проект ASP.NET Core 6 в Visual Studio. Выполнение этих шагов приведет к созданию нового проекта веб-API ASP.NET Core 6 в Visual Studio 2022:

1. Запустите интегрированную среду разработки Visual Studio 2022.
2. Нажмите «Создать новый проект».
3. В окне «Создать новый проект» выберите «ASP.NET Core Web API» из списка отображаемых шаблонов.
4. Нажмите “Далее.
5. В окне «Настроить новый проект» укажите имя и местоположение нового проекта.
6. При желании установите флажок «Поместить решение и проект в один каталог», в зависимости от ваших предпочтений.
7. Нажмите “Далее.
8. В следующем окне «Дополнительная информация» снимите флажок «Использовать контроллеры…», поскольку в этом примере мы будем использовать минимальные API. В поле «Тип аутентификации» оставьте значение «Нет» (по умолчанию).
9. Убедитесь, что флажки «Включить Docker», «Настроить HTTPS» и «Включить поддержку Open API» сняты, поскольку мы не будем здесь использовать ни одну из этих функций.
10. Нажмите Создать.

Мы будем использовать этот проект веб-API ASP.NET Core 6 для создания минимальных конечных точек API и реализации управления версиями API в разделах ниже.

Установите пакеты NuGet для управления версиями API.

Минимальные API-интерфейсы ASP.NET Core 6 поддерживают управление версиями с использованием любого из этих трех пакетов:

• Asp.Versioning.Http — используется для поддержки управления версиями в минимальных API.
• Asp.Versioning.Mvc — используется для обеспечения поддержки управления версиями в приложениях MVC Core.
• Asp.Versioning.Mvc.ApiExplorer — используется для обеспечения поддержки в расширениях API Explorer для управления версиями API ASP.NET Core.

Если вы успешно создали проект веб-приложения ASP.NET Core 6 в Visual Studio 2022, следующее, что вам нужно сделать, — это добавить в проект необходимые пакеты NuGet. Для этого выберите проект в окне обозревателя решений, щелкните правой кнопкой мыши и выберите «Управление пакетами NuGet…». В окне диспетчера пакетов NuGet найдите следующий пакет и установите его.

Asp.Versioning.Http

Альтернативно вы можете установить пакет через консоль диспетчера пакетов NuGet, как показано ниже.

PM> Install-Package Asp.Versioning.Http

Добавьте поддержку управления версиями API в коллекцию сервисов в ASP.NET Core 6.

Чтобы добавить поддержку управления версиями API в коллекцию сервисов для минимального API, вам следует написать следующий код в файле Program.cs:

builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});

Обратите внимание, как указана версия API по умолчанию. Свойство ApiVersionReader используется для указания ключа, который будет использоваться клиентом для передачи версии API при вызове конечных точек API. Если значение свойства AssumeDefaultVersionWhenUnspecified равно true, будет использоваться версия API по умолчанию, если клиент не указал версию API.

Обратите внимание, что вы можете объединить HeaderApiVersionReader и QueryStringApiVersionReader, чтобы клиенты могли указывать информацию о версии несколькими способами при вызове конечных точек API.

services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
    options.ApiVersionReader =
    ApiVersionReader.Combine(
       new HeaderApiVersionReader("Api-Version"),
       new QueryStringApiVersionReader("Query-String-Version"));
});

Добавьте версии API, используя набор версий в ASP.NET Core 6.

Теперь определите новый набор версий для вашего API, используя следующий код.

var versionSet = app.NewApiVersionSet()
                    .HasApiVersion(1.0)
                    .HasApiVersion(2.0)
                    .ReportApiVersions()
                    .Build();

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

Создайте минимальные конечные точки API в ASP.NET Core 6.

Мы создадим здесь две конечные точки, чтобы упростить задачу и сосредоточиться на управлении версиями наших минимальных API. Напишите следующий код в файле Program.cs, чтобы создать две конечные точки.

app.MapGet("/GetMessage", () => "This is an example of a minimal API").WithApiVersionSet(versionSet).MapToApiVersion(1.0);
app.MapGet("/GetText", () => "This is yet another example of a minimal API").WithApiVersionSet(versionSet).WithApiVersionSet(versionSet)
.IsApiVersionNeutral();

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

Вот полный исходный код файла Program.cs для справки:

using Asp.Versioning;
using Asp.Versioning.Conventions;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ReportApiVersions = true;
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
});
var app = builder.Build();
var versionSet = app.NewApiVersionSet()
                    .HasApiVersion(1.0)
                    .HasApiVersion(2.0)
                    .ReportApiVersions()
                    .Build();
// Configure the HTTP request pipeline.
app.MapGet("/GetMessage", () => "This is an example of a minimal API").WithApiVersionSet(versionSet).HasApiVersion(new ApiVersion(2, 0));
app.MapGet("/GetText", () => "This is another example of a minimal API").WithApiVersionSet(versionSet).IsApiVersionNeutral();
app.Run();

Выполните минимальные конечные точки API

Теперь нажмите клавишу F5 в Visual Studio 2022 IDE, чтобы запустить приложение. На следующем снимке экрана (рис. 1) показана ошибка, с которой вы столкнетесь, если вызовете конечную точку /getmessage без указания ключа версии API в заголовке запроса.

ИДГ

На следующем снимке экрана (рис. 2) показано, как будут выглядеть выходные данные, если вы укажете ключ версии API в заголовке запроса и снова вызовете конечную точку /getmessage.

ИДГ

Поскольку конечная точка /gettext помечена как нейтральная к версии API, вам не нужно указывать версию API при вызове этой конечной точки. Когда вы выполните конечную точку /gettext, ответ будет выглядеть так, как показано на снимке экрана (рис. 3) ниже.

ИДГ

Поскольку это минимальная реализация, мы не использовали контекст данных, базу данных, класс репозитория или даже какие-либо классы модели. Мы просто определили две простые конечные точки API, чтобы проиллюстрировать, как мы можем управлять версиями минимальных API в ASP.NET Core 6.