Programovanie

Ako používať spravovanie verzií API v ASP.NET Core

Pri vývoji API by ste mali mať na pamäti jednu vec: Zmena je nevyhnutná. Keď vaše rozhranie API dosiahne bod, v ktorom je potrebné pridať ďalšie zodpovednosti, mali by ste zvážiť verziu vášho API. Preto budete potrebovať stratégiu vytvárania verzií.

Existuje niekoľko prístupov k verzovaniu API a každý z nich má svoje klady a zápory. Tento článok bude pojednávať o výzvach verzovania API a o tom, ako môžete pracovať s balíkom Microsoft ASP.NET Core MVC Versioning to version RESTful APIs built in ASP.NET Core. Viac informácií o verziách webových rozhraní API sa dočítate v mojom predchádzajúcom článku tu.

Vytvorte projekt rozhrania ASP.NET Core 3.1 API

Najprv si vytvoríme projekt ASP.NET Core v Visual Studio. Za predpokladu, že je vo vašom systéme nainštalované Visual Studio 2019, postupujte podľa krokov uvedených nižšie a vytvorte nový projekt ASP.NET Core v Visual Studio.

  1. Spustite Visual Studio IDE.
  2. Kliknite na „Vytvoriť nový projekt“.
  3. V okne „Vytvoriť nový projekt“ vyberte zo zobrazeného zoznamu šablón „Webová aplikácia ASP.NET Core“.
  4. Kliknite na Ďalej.
  5. V nasledujúcom okne „Konfigurácia nového projektu“ zadajte názov a umiestnenie nového projektu.
  6. Kliknite na tlačidlo Vytvoriť.
  7. V okne „Vytvoriť novú webovú aplikáciu ASP.NET Core“ vyberte z rozbaľovacieho zoznamu v hornej časti .NET Core ako runtime a ASP.NET Core 3.1 (alebo novší). Budem tu používať ASP.NET Core 3.1.
  8. Vyberte „API“ ako šablónu projektu a vytvorte novú aplikáciu API ASP.NET Core.
  9. Skontrolujte, či nie sú začiarknuté políčka „Povoliť podporu Docker“ a „Konfigurovať pre HTTPS“, pretože tu nebudeme tieto funkcie používať.
  10. Skontrolujte, či je overenie nastavené na „Bez overenia“, pretože tiež nebudeme používať overenie.
  11. Kliknite na tlačidlo Vytvoriť.

Týmto sa vytvorí nový projekt rozhrania ASP.NET Core API v Visual Studio. Vyberte priečinok Riešenie ovládačov v okne Prieskumníka riešení a kliknutím na „Pridať -> Ovládač ...“ vytvorte nový ovládač s názvom DefaultController.

Nahraďte zdrojový kód triedy DefaultController nasledujúcim kódom.

  [Route („api / [controller]“)]

[ApiController]

verejná trieda DefaultController: ControllerBase

    {

string [] autori = nový reťazec []

{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

[HttpGet]

verejné IEnumerable Get ()

        {

návratoví autori;

        }

    }

Tento ovládač použijeme v ďalších častiach tohto článku.

Ak chcete implementovať spravovanie verzií API v ASP.NET Core, musíte urobiť nasledovné:

  1. Nainštalujte si balík verzií ASP.NET Core MVC.
  2. Nakonfigurujte spravovanie verzií API v triede Startup.
  3. Anotujte ovládače a akcie príslušnými atribútmi.

Nainštalujte si balík verzií ASP.NET Core MVC

ASP.NET Core poskytuje podporu pre verzovanie rozhraní API out-of-the-box. Ak chcete využiť verzovanie API, musíte si len nainštalovať balík Microsoft.AspNetCore.Mvc.Versioning z NuGet. Môžete to urobiť buď prostredníctvom správcu balíkov NuGet vo vnútri IDE Visual Studio 2019, alebo vykonaním nasledujúceho príkazu v konzole správcu balíkov NuGet:

Inštalačný balík Microsoft.AspNetCore.Mvc.Versioning

Upozorňujeme, že ak používate webové rozhranie ASP.NET Web API, mali by ste pridať balík Microsoft.AspNet.WebApi.Versioning.

Nakonfigurujte spravovanie verzií API v ASP.NET Core

Teraz, keď je vo vašom projekte nainštalovaný balík nevyhnutný na spravovanie verzií vášho API, môžete nakonfigurovať spravovanie verzií API v metóde ConfigureServices triedy Startup. Nasledujúci úryvok kódu ilustruje, ako je to možné dosiahnuť.

public void ConfigureServices (služby IServiceCollection)

{

services.AddControllers ();

services.AddApiVersioning ();

}

Keď zadáte požiadavku Get na vaše API, zobrazí sa vám chyba uvedená na obrázku 1.

Ak chcete vyriešiť túto chybu, môžete pri pridávaní verzovacích služieb API do kontajnera určiť predvolenú verziu. Môžete tiež použiť predvolenú verziu, ak v žiadosti nie je uvedená verzia. Nasledujúci úryvok kódu ukazuje, ako môžete nastaviť predvolenú verziu na 1,0 pomocou vlastnosti AssumeDefaultVersionWhenUnspecified, ak v žiadosti nie sú k dispozícii informácie o verzii.

services.AddApiVersioning (config =>

{

config.DefaultApiVersion = nová ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

});

Všimnite si, ako sa hlavná verzia a vedľajšia verzia odovzdávajú konštruktoru triedy ApiVersion v čase priradenia predvolenej verzie. Vlastnosť AssumeDefaultVersionWhenUnspecified môže obsahovať hodnotu true alebo false. Ak je to pravda, použije sa predvolená verzia zadaná pri konfigurácii spravovania verzií API, ak nie sú k dispozícii žiadne informácie o verzii.

Celý zdrojový kód metódy ConfigureServices je uvedený nižšie pre vašu potrebu.

public void ConfigureServices (služby IServiceCollection)

{

services.AddControllers ();

services.AddApiVersioning (config =>

    {

config.DefaultApiVersion = nová ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Pretože ste nezadali žiadne informácie o verzii, všetky koncové body budú mať predvolenú verziu 1.0.

Nahláste všetky podporované verzie rozhrania API

Možno budete chcieť informovať klientov rozhrania API o všetkých podporovaných verziách. Ak to chcete urobiť, mali by ste využiť výhodu vlastnosti ReportApiVersions, ktorá je uvedená v útržku kódu uvedenom nižšie.

services.AddApiVersioning (config =>

{

config.DefaultApiVersion = nová ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

config.ReportApiVersions = true;

});

Používajte verzie v ovládači a akčné metódy

Teraz pridajme niekoľko podporovaných verzií do nášho ovládača pomocou atribútov, ktoré sú uvedené v útržku kódu uvedenom nižšie.

  [Route („api / [controller]“)]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

verejná trieda DefaultController: ControllerBase

    {

string [] autori = nový reťazec []

{"Joydip Kanjilal", "Steve Smith", "Anand John"};

[HttpGet]

verejné IEnumerable Get ()

        {

návratoví autori;

        }

    }

Keď zadáte požiadavku na získanie od klienta HTTP, ako je napríklad Poštár, bude tu uvedená správa.

Môžete tiež nahlásiť zastarané verzie. Za týmto účelom by ste mali metóde ApiVersion odovzdať ďalší parameter, ako je znázornené v útržku kódu uvedenom nižšie.

[ApiVersion ("1.0", zastarané = true)]

Namapujte na konkrétnu verziu metódy akcie

Existuje ďalší dôležitý atribút s názvom MapToApiVersion. Môžete ho použiť na mapovanie na konkrétnu verziu metódy akcie. Nasledujúci úryvok kódu ukazuje, ako je to možné dosiahnuť.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

verejný reťazec Get (int id)

{

návratoví autori [id];

}

Kompletný príklad verzií API v ASP.NET Core

Tu je kompletný zdrojový kód DefaultController pre vašu referenciu.

[Route („api / [controller]“)]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

verejná trieda DefaultController: ControllerBase

{

string [] autori = nový reťazec []

{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

[HttpGet]

verejné IEnumerable Get ()

  {

návratoví autori;

  }

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

verejný reťazec Get (int id)

  {

návratoví autori [id];

  }

}

Stratégie verzovania API v ASP.NET Core

Existuje niekoľko spôsobov, ako môžete verzie API vytvoriť v ASP.NET Core. V tejto časti preskúmame každú z nich.

Informácie o verzii odovzdajte ako parametre QueryString

V takom prípade by ste zvyčajne odovzdávali informácie o verzii ako súčasť reťazca dotazu, ako je uvedené na nižšie uvedenej adrese URL.

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

Predajte informácie o verzii v hlavičkách HTTP

Ak chcete odovzdať informácie o verzii v hlavičkách HTTP, mali by ste ich nastaviť v metóde ConfigureServices, ako je uvedené v útržku kódu uvedenom nižšie.

services.AddApiVersioning (config =>

{

config.DefaultApiVersion = nová ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

config.ReportApiVersions = true;

config.ApiVersionReader = nový HeaderApiVersionReader ("verzia api");

});

Po nastavení môžete vyvolať metódu akcie týkajúce sa konkrétnej verzie API, ako je to znázornené na obrázku 3.

Zadajte informácie o verzii do adresy URL

Ďalším spôsobom poskytovania informácií o verzii je odovzdávanie informácií o verzii ako časti trasy. Toto je najjednoduchší spôsob verzovania vášho API, ale existujú určité výhrady. Ak použijete túto stratégiu, vaši klienti budú musieť najskôr aktualizovať adresu URL pri každom vydaní novej verzie rozhrania API. Tento prístup následne porušuje základný princíp REST, ktorý uvádza, že URL konkrétneho zdroja by sa nikdy nemalo meniť.

Ak chcete implementovať túto stratégiu spravovania verzií, mali by ste zadať informácie o trase v radiči, ako je uvedené nižšie.

[Route ("api / v {verzia: apiVersion} / [controller]")]

Nasledujúci zoznam kódov ukazuje, ako to môžete nastaviť vo svojej triede ovládačov.

[Route ("api / v {verzia: apiVersion} / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

verejná trieda DefaultController: ControllerBase

    {

string [] autori = nový reťazec []

{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

[HttpGet]

verejné IEnumerable Get ()

        {

návratoví autori;

        }

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

verejný reťazec Get (int id)

        {

návratoví autori [id];

        }

    }

Takto môžete zavolať predvolený protokol HTTP a získať metódu triedy DefaultController.

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

Ak chcete vyvolať inú metódu HTTP GET, t. J. Tú, ktorá prijíma parameter, zadajte vo webovom prehliadači alebo v klientovi HTTP, ako je napríklad Poštár, nasledujúce.

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

Zastarajte podporu jednej alebo viacerých verzií vášho API

Predpokladajme, že máte viac verzií vášho API, ale chcete ukončiť podporu jednej alebo viacerých z nich. Môžete to urobiť ľahko - stačí zadať vlastnosť Deprecated triedy ApiVersionAttribute na hodnotu true, ako je to uvedené v útržku kódu uvedenom nižšie.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", zastarané = true)]

[ApiVersion ("2.0")]

verejná trieda DefaultController: ControllerBase

{

// Obvyklý kód

}

Verzovanie API v ASP.NET Core je teraz bezproblémové vďaka zavedeniu balíka Microsoft.AspNetCore.Mvc.Versioning. Existuje niekoľko spôsobov, ako vytvoriť verziu vášho API - stačí sa rozhodnúť najlepšiu stratégiu na základe vašich požiadaviek. Pre svoje API môžete tiež použiť niekoľko schém spravovania verzií. To dodáva veľkú flexibilitu, pretože klienti si môžu vybrať ktorúkoľvek z podporovaných verzií.

Ako urobiť viac v ASP.NET Core:

  • Ako používať objekty na prenos dát v ASP.NET Core 3.1
  • Ako spracovať chyby 404 v ASP.NET Core MVC
  • Ako používať vkladanie závislostí do filtrov akcií v ASP.NET Core 3.1
  • Ako používať vzor možností v ASP.NET Core
  • Ako používať smerovanie koncového bodu v ASP.NET Core 3.0 MVC
  • Ako exportovať údaje do programu Excel v ASP.NET Core 3.0
  • Ako používať LoggerMessage v ASP.NET Core 3.0
  • Ako posielať e-maily v ASP.NET Core
  • Ako prihlásiť údaje na server SQL Server v ASP.NET Core
  • Ako plánovať úlohy pomocou Quartz.NET v ASP.NET Core
  • Ako vrátiť dáta z webového rozhrania ASP.NET Core Web API
  • Ako formátovať údaje odpovedí v ASP.NET Core
  • Ako konzumovať webové rozhranie API ASP.NET Core pomocou nástroja RestSharp
  • Ako vykonávať asynchronné operácie pomocou nástroja Dapper
  • Ako používať príznaky funkcií v ASP.NET Core
  • Ako používať atribút FromServices v ASP.NET Core
  • Ako pracovať s cookies v ASP.NET Core
  • Ako pracovať so statickými súbormi v ASP.NET Core
  • Ako používať middleware na prepisovanie adries URL v ASP.NET Core
  • Ako implementovať obmedzenie rýchlosti v ASP.NET Core
  • Ako používať Azure Application Insights v ASP.NET Core
  • Používanie pokročilých funkcií NLog v ASP.NET Core
  • Ako spracovať chyby v webovom rozhraní API ASP.NET
  • Ako implementovať globálne spracovanie výnimiek v ASP.NET Core MVC
  • Ako spracovať nulové hodnoty v ASP.NET Core MVC
  • Pokročilé spravovanie verzií v webovom rozhraní API ASP.NET Core
  • Ako pracovať s pracovnými službami v ASP.NET Core
  • Ako používať rozhranie Data Protection API v ASP.NET Core
  • Ako používať podmienený middleware v ASP.NET Core
  • Ako pracovať so stavom relácie v ASP.NET Core
  • Ako písať efektívne radiče v ASP.NET Core
$config[zx-auto] not found$config[zx-overlay] not found