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

Когато разработвате API, трябва да имате предвид едно нещо: Промяната е неизбежна. Когато вашият API достигне точка, в която трябва да добавите повече отговорности, трябва да помислите за версия на вашия API. Следователно ще ви е необходима стратегия за версии.

Има няколко подхода към API на версиите и всеки от тях има своите плюсове и минуси. Тази статия ще обсъди предизвикателствата на версирането на API и как можете да работите с пакета за версиране на ASP.NET Core MVC на Microsoft към версия RESTful API, вградени в ASP.NET Core. Можете да прочетете повече за създаването на версии на уеб API в предишната ми статия тук. 

Създайте проект за API на ASP.NET Core 3.1

Първо, нека създадем проект на ASP.NET Core в Visual Studio. Ако приемем, че Visual Studio 2019 е инсталиран във вашата система, следвайте стъпките, описани по-долу, за да създадете нов проект ASP.NET Core в Visual Studio.

  1. Стартирайте Visual Studio IDE.
  2. Кликнете върху „Създаване на нов проект“.
  3. В прозореца „Създаване на нов проект“ изберете „ASP.NET Core Web Application“ от показания списък с шаблони.
  4. Щракнете върху Напред.
  5. В показания след това прозорец „Конфигуриране на вашия нов проект“ посочете името и местоположението на новия проект.
  6. Щракнете върху Създаване.
  7. В прозореца „Създаване на ново уеб приложение на ASP.NET Core“ изберете .NET Core като време на изпълнение и ASP.NET Core 3.1 (или по-нова версия) от падащия списък в горната част. Тук ще използвам ASP.NET Core 3.1.
  8. Изберете „API“ като шаблон на проекта, за да създадете ново приложение на ASP.NET Core API. 
  9. Уверете се, че квадратчетата „Активиране на поддръжката на Docker“ и „Конфигуриране за HTTPS“ са отметнати, тъй като тук няма да използваме тези функции.
  10. Уверете се, че удостоверяването е зададено като „Без удостоверяване“, тъй като и ние няма да използваме удостоверяване.
  11. Щракнете върху Създаване. 

Това ще създаде нов проект за ASP.NET Core API в Visual Studio. Изберете папката за решение Controllers в прозореца Solution Explorer и щракнете върху „Add -> Controller ...“, за да създадете нов контролер с име DefaultController.

Заменете изходния код на класа DefaultController със следния код.

    [Маршрут („api / [контролер]“)]

    [ApiController]

    публичен клас DefaultController: ControllerBase

    {

        низ [] автори = нов низ []

        {"Джойдип Канджилал", "Стив Смит", "Стивън Джоунс"};

        [HttpGet]

        публичен IEnumerable Get ()

        {

            връщане на автори;

        }

    }

Ще използваме този контролер в следващите раздели на тази статия.

За да приложите API за версии в ASP.NET Core, трябва да направите следното:

  1. Инсталирайте пакета за управление на версиите ASP.NET Core MVC.
  2. Конфигурирайте версирането на API в класа Startup.
  3. Коментирайте контролерите и действията с подходящи атрибути.

Инсталирайте пакета за управление на версиите ASP.NET Core MVC

ASP.NET Core предоставя поддръжка на API за версия на версии. За да използвате API за версиониране, всичко, което трябва да направите, е да инсталирате пакета Microsoft.AspNetCore.Mvc.Versioning от NuGet. Можете да направите това или чрез диспечера на пакети NuGet вътре в IDE на Visual Studio 2019, или като изпълните следната команда в конзолата на диспечера на пакети NuGet:

Инсталирайте пакета Microsoft.AspNetCore.Mvc.Versioning

Имайте предвид, че ако използвате ASP.NET Web API, трябва да добавите пакета Microsoft.AspNet.WebApi.Versioning.

Конфигурирайте API за управление на версии в ASP.NET Core

След като във вашия проект е инсталиран необходимият пакет за версиране на вашия API, можете да конфигурирате версирането на API в метода ConfigureServices на класа Startup. Следният кодов фрагмент илюстрира как това може да се постигне.

публична невалидна ConfigureServices (услуги на IServiceCollection)

{

  услуги.AddControllers ();

  services.AddApiVersioning ();

}

Когато направите заявка за получаване на вашия API, ще ви се покаже грешката, показана на фигура 1.

За да разрешите тази грешка, можете да посочите версията по подразбиране, когато добавяте услугите за управление на API на контейнера. Може да искате да използвате и версия по подразбиране, ако в заявката не е посочена версия. Следният кодов фрагмент показва как можете да зададете версия по подразбиране като 1.0, като използвате свойството AssumeDefaultVersionWhenUnspecified, ако информацията за версията не е налична в заявката.

услуги.AddApiVersioning (config =>

{

   config.DefaultApiVersion = нов ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Обърнете внимание как основната версия и второстепенната версия се предават на конструктора на класа ApiVersion по време на присвояване на версията по подразбиране. Свойството AssumeDefaultVersionWhenUnspecified може да съдържа истински или фалшиви стойности. Ако е вярно, версията по подразбиране, посочена при конфигуриране на версирането на API, ще се използва, ако няма налична информация за версията.

Пълният изходен код на метода ConfigureServices е даден по-долу за справка.

публична невалидна ConfigureServices (услуги на IServiceCollection)

{

    услуги.AddControllers ();

    услуги.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = нов ApiVersion (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Тъй като не сте посочили информация за версията, всички крайни точки ще имат версията по подразбиране 1.0.

Отчетете всички поддържани версии на вашия API

Може да искате да уведомите клиентите на API за всички поддържани версии. За да направите това, трябва да се възползвате от свойството ReportApiVersions, както е показано в кодовия фрагмент, даден по-долу.

услуги.AddApiVersioning (config =>

{

  config.DefaultApiVersion = нов ApiVersion (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = вярно;

});

Използвайте версии в контролера и методи за действие

Сега нека добавим няколко поддържани версии към нашия контролер, използвайки атрибути, както е показано в кодовия фрагмент, даден по-долу.

    [Маршрут („api / [контролер]“)]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    публичен клас DefaultController: ControllerBase

    {

        низ [] автори = нов низ []

        {"Джойдип Канджилал", "Стив Смит", "Ананд Джон"};

        [HttpGet]

        публичен IEnumerable Get ()

        {

            връщане на автори;

        }

    }

Когато направите заявка за получаване от HTTP клиент като Postman, ето как ще се отчитат версиите.

Можете да съобщите и за остарелите версии. За да направите това, трябва да предадете допълнителен параметър на метода ApiVersion, както е показано в кодовия фрагмент, даден по-долу.

[ApiVersion ("1.0", оттеглено = вярно)]

Съпоставяне с конкретна версия на метод за действие

Има още един важен атрибут, наречен MapToApiVersion. Можете да го използвате, за да присвоите конкретна версия на метод за действие. Следният кодов фрагмент показва как може да се постигне това.

[HttpGet („{id}“)]

[MapToApiVersion ("2.0")]

публичен низ Get (int id)

{

   връщане на автори [id];

}

Пълен пример за версия на API в ASP.NET Core

Ето пълния изходен код на DefaultController за справка.

[Маршрут („api / [контролер]“)]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

публичен клас DefaultController: ControllerBase

{

  низ [] автори = нов низ []

  {"Джойдип Канджилал", "Стив Смит", "Стивън Джоунс"};

  [HttpGet]

  публичен IEnumerable Get ()

  {

      връщане на автори;

  }

  [HttpGet („{id}“)]

  [MapToApiVersion ("2.0")]

  публичен низ Get (int id)

  {

     връщане на автори [id];

  }

}

Стратегии за управление на API в ASP.NET Core

Има няколко начина, по които можете да версия на вашия API в ASP.NET Core. В този раздел ще разгледаме всеки от тях.

Предавайте информация за версията като параметри QueryString

В този случай обикновено предавате информацията за версията като част от низа на заявката, както е показано в URL адреса, даден по-долу.

//localhost:25718/api/default?api-version=1.0

Предавайте информация за версията в HTTP заглавките

Ако трябва да предавате информация за версията в HTTP заглавията, трябва да я настроите в метода ConfigureServices, както е показано в кодовия фрагмент, даден по-долу.

услуги.AddApiVersioning (config =>

{

   config.DefaultApiVersion = нов ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = вярно;

   config.ApiVersionReader = нов HeaderApiVersionReader ("api-версия");

});

След като това е настроено, можете да извикате метод за действие, отнасящ се до определена версия на API, както е показано на Фигура 3.

Предайте информация за версията в URL адреса

Още един метод за предаване на информация за версията е предаването на информация за версията като част от маршрута. Това е най-простият начин за версия на вашия API, но има някои предупреждения. Първо, ако използвате тази стратегия, вашите клиенти ще трябва да актуализират URL адреса, когато бъде пусната нова версия на API. Следователно този подход нарушава основен принцип на REST, който гласи, че URL адресът на определен ресурс никога не трябва да се променя.

За да приложите тази стратегия за управление на версиите, трябва да посочите информацията за маршрута във вашия контролер, както е показано по-долу.

[Маршрут („api / v {версия: apiVersion} / [контролер]“)]

Следният списък с кодове показва как можете да настроите това във вашия клас на контролер.

[Маршрут („api / v {версия: apiVersion} / [контролер]“)]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

публичен клас DefaultController: ControllerBase

    {

        низ [] автори = нов низ []

        {"Джойдип Канджилал", "Стив Смит", "Стивън Джоунс"};

        [HttpGet]

        публичен IEnumerable Get ()

        {

            връщане на автори;

        }

        [HttpGet („{id}“)]

        [MapToApiVersion ("2.0")]

        публичен низ Get (int id)

        {

            връщане на автори [id];

        }

    }

Ето как можете да извикате HTTP по подразбиране, за да получите метода на класа DefaultController.

//localhost:25718/api/v1.0/default

За да извикате другия HTTP GET метод, т.е. този, който приема параметър, посочете следното или в уеб браузъра, или в HTTP клиент като Postman.

//localhost:25718/api/v2.0/default/1

Оттегляне на една или повече версии на вашия API

Да предположим, че имате няколко версии на вашия API, но бихте искали да оттеглите една или повече от тях. Можете да направите това лесно - просто трябва да посочите оттегленото свойство на класа ApiVersionAttribute на true, както е показано в кодовия фрагмент, даден по-долу.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", оттеглено = вярно)]

[ApiVersion ("2.0")]

публичен клас DefaultController: ControllerBase

{

     // Обикновен код

}

Версионирането на API в ASP.NET Core вече е безпроблемно благодарение на въвеждането на пакета Microsoft.AspNetCore.Mvc.Versioning. Има няколко начина за версия на вашия API - просто трябва да решите най-добрата стратегия въз основа на вашите изисквания. Можете също да използвате множество схеми за версии за вашия API. Това добавя голяма гъвкавост, тъй като клиентите могат да изберат някоя от поддържаните схеми за управление на версиите.

Как да направите повече в ASP.NET Core:

  • Как да използвам обекти за прехвърляне на данни в ASP.NET Core 3.1
  • Как да се справя с 404 грешки в ASP.NET Core MVC
  • Как да използвам инжектиране на зависимост във филтри за действие в ASP.NET Core 3.1
  • Как да използвам шаблона за опции в ASP.NET Core
  • Как да използвам маршрутизиране на крайни точки в ASP.NET Core 3.0 MVC
  • Как да експортирам данни в Excel в ASP.NET Core 3.0
  • Как да използвам LoggerMessage в ASP.NET Core 3.0
  • Как да изпращате имейли в ASP.NET Core
  • Как да регистрирам данни в SQL Server в ASP.NET Core
  • Как да планирате работни места с помощта на Quartz.NET в ASP.NET Core
  • Как да върнете данни от ASP.NET Core Web API
  • Как да форматирате данните за отговор в ASP.NET Core
  • Как да консумирате ASP.NET Core Web API с помощта на RestSharp
  • Как да извършвате асинхронни операции с помощта на Dapper
  • Как да използваме флагове на функции в ASP.NET Core
  • Как да използвам атрибута FromServices в ASP.NET Core
  • Как да работите с бисквитки в ASP.NET Core
  • Как да работя със статични файлове в ASP.NET Core
  • Как да използвам URL пренаписване на Middleware в ASP.NET Core
  • Как да приложим ограничаване на скоростта в ASP.NET Core
  • Как да използвам Azure Application Insights в ASP.NET Core
  • Използване на разширени функции на NLog в ASP.NET Core
  • Как да се справим с грешки в ASP.NET Web API
  • Как да приложим обработка на глобални изключения в ASP.NET Core MVC
  • Как да се справя с нулеви стойности в ASP.NET Core MVC
  • Разширено създаване на версии в ASP.NET Core Web API
  • Как да работя с услуги за работници в ASP.NET Core
  • Как да използвам API за защита на данните в ASP.NET Core
  • Как да използвам условен мидълуер в ASP.NET Core
  • Как да работите със състоянието на сесията в ASP.NET Core
  • Как да пишете ефективни контролери в ASP.NET Core