Kaip naudoti API versijas „ASP.NET Core“

Kurdami API, turėtumėte nepamiršti vieno dalyko: pokyčiai neišvengiami. Kai jūsų API pasiekia tašką, kur jums reikia pridėti daugiau atsakomybės, turėtumėte apsvarstyti savo versijos versiją. Taigi jums reikės versijos strategijos.

API versijose yra keletas būdų, ir kiekvienas iš jų turi savo pliusų ir minusų. Šiame straipsnyje bus aptarti API versijų iššūkiai ir tai, kaip galite dirbti su „Microsoft“ ASP.NET Core MVC versijų paketu į RESTful versijos API, pastatytą ASP.NET Core. Daugiau apie žiniatinklio API versijas galite perskaityti mano ankstesniame straipsnyje čia.

Sukurkite ASP.NET Core 3.1 API projektą

Pirmiausia sukurkime ASP.NET Core projektą „Visual Studio“. Darant prielaidą, kad „Visual Studio 2019“ yra įdiegta jūsų sistemoje, atlikite toliau nurodytus veiksmus, kad sukurtumėte naują „ASP.NET Core“ projektą „Visual Studio“.

Paleiskite „Visual Studio IDE“.
Spustelėkite „Sukurti naują projektą“.
Lange „Kurti naują projektą“ iš rodomų šablonų sąrašo pasirinkite „ASP.NET Core Web Application“.
Spustelėkite Pirmyn.
Tada rodomame lange „Konfigūruoti naują projektą“ nurodykite naujo projekto pavadinimą ir vietą.
Spustelėkite Sukurti.
Lange „Kurti naują ASP.NET pagrindinę žiniatinklio programą“ viršuje esančiame išskleidžiamajame sąraše pasirinkite .NET Core kaip vykdymo laiką ir ASP.NET Core 3.1 (ar naujesnę). Čia naudosiu ASP.NET Core 3.1.
Pasirinkite „API“ kaip projekto šabloną, kad sukurtumėte naują ASP.NET Core API programą.
Įsitikinkite, kad nepažymėti žymės langeliai „Įgalinti„ Docker “palaikymą“ ir „Konfigūruoti HTTPS“, nes čia nenaudosime tų funkcijų.
Įsitikinkite, kad autentifikavimas nustatytas kaip „Be autentifikavimo“, nes mes taip pat nenaudosime autentifikavimo.
Spustelėkite Sukurti.

Tai sukurs naują ASP.NET Core API projektą „Visual Studio“. Lange Solution Explorer pasirinkite „Controllers solution“ aplanką ir spustelėkite „Add -> Controller…“, kad sukurtumėte naują valdiklį pavadinimu „DefaultController“.

Pakeiskite DefaultController klasės šaltinio kodą šiuo kodu.

  [Maršrutas („api / [valdiklis]“)]
  [ApiController]
  viešoji klasė DefaultController: ControllerBase
    {
  eilutė [] autoriai = nauja eilutė []
  {"Joydipas Kanjilalas", "Steve'as Smithas", "Stephenas Jonesas"};
  [HttpGet]
  public IEnumerable Get ()
        {
  grįžtantys autoriai;
        }
    }

Šį valdiklį naudosime tolesniuose šio straipsnio skyriuose.

Norėdami įdiegti API versijas „ASP.NET Core“, turite atlikti šiuos veiksmus:

Įdiekite „ASP.NET Core MVC Versioning“ paketą.
Konfigūruokite API versijas „Startup“ klasėje.
Pažymėkite valdiklius ir veiksmus su tinkamais atributais.

Įdiekite „ASP.NET Core MVC Versioning“ paketą

ASP.NET Core palaiko API versijas iš karto. Norint pasinaudoti API versijomis, viskas, ką jums reikia padaryti, yra įdiegti „Microsoft.AspNetCore.Mvc.Versioning“ paketą iš „NuGet“. Tai galite padaryti naudodami „NuGet“ paketų tvarkytuvę „Visual Studio 2019 IDE“ arba vykdydami šią komandą „NuGet“ paketų tvarkyklės konsolėje:

„Microsoft.AspNetCore.Mvc.“ versijų diegimo paketas

Atminkite, kad jei naudojate ASP.NET žiniatinklio API, turėtumėte pridėti „Microsoft.AspNet.WebApi.Versioning“ paketą.

Konfigūruokite API versijas programoje „ASP.NET Core“

Dabar, kai jūsų projekte įdiegtas būtinas API versijos paketas, galite konfigūruoti API versijas „Startup“ klasės „ConfigureServices“ metodu. Šis kodo fragmentas parodo, kaip tai galima pasiekti.

public void „ConfigureServices“ („IServiceCollection“ paslaugos)
{
  paslaugos.AddControllers ();
  paslaugos.AddApiVersioning ();
}

Kai pateiksite „API“ užklausą, jums bus pateikta 1 paveiksle pavaizduota klaida.

Norėdami išspręsti šią klaidą, galite nurodyti numatytąją versiją, kai į sudėtinį rodinį pridedate API versijų teikimo paslaugas. Taip pat galite naudoti numatytąją versiją, jei versija nenurodyta užklausoje. Šis kodo fragmentas rodo, kaip galite nustatyti numatytąją versiją kaip 1.0 naudodami ypatybę „AssumeDefaultVersionWhenUnspecified“, jei versijoje informacijos nėra užklausoje.

paslaugos.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nauja ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
});

Atkreipkite dėmesį, kaip priskiriant numatytąją versiją, pagrindinė ir antroji versijos versijos yra perduotos „ApiVersion“ klasės konstruktoriui. Ypatybėje „AssumeDefaultVersionWhenUnspecified“ gali būti teisingos arba klaidingos vertės. Jei tai tiesa, bus naudojama numatytoji versija, nurodyta konfigūruojant API versijas, jei nėra versijos informacijos.

Visas jūsų „ConfigureServices“ metodo šaltinio kodas pateiktas jūsų nuoroda.

public void „ConfigureServices“ („IServiceCollection“ paslaugos)
{
  paslaugos.AddControllers ();
  paslaugos.AddApiVersioning (config =>
    {
  config.DefaultApiVersion = nauja ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
    });
}

Kadangi nenurodėte jokios versijos informacijos, visi galiniai taškai turės numatytąją 1.0 versiją.

Pranešti apie visas palaikomas API versijas

Galbūt norėsite pranešti API klientams apie visas palaikomas versijas. Norėdami tai padaryti, turėtumėte pasinaudoti „ReportApiVersions“ ypatybe, kaip parodyta toliau pateiktame kodo fragmente.

paslaugos.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nauja ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = tiesa;
});

Naudokite valdiklio versijas ir veiksmų metodus

Dabar pridėkime keletą palaikomų versijų prie valdiklio naudodami atributus, kaip parodyta toliau pateiktame kodo fragmente.

  [Maršrutas („api / [valdiklis]“)]
  [ApiController]
  [ApiVersion („1.0“)]
  [ApiVersion („1.1“)]
  [ApiVersion („2.0“)]
  viešoji klasė DefaultController: ControllerBase
    {
  eilutė [] autoriai = nauja eilutė []
  {"Joydip Kanjilal", "Steve Smith", "Anand John"};
  [HttpGet]
  public IEnumerable Get ()
        {
  grįžtantys autoriai;
        }
    }

Kai pateikiate užklausą gauti iš HTTP kliento, pvz., „Postman“, štai kaip bus pranešta apie versijas.

Taip pat galite pranešti apie nebenaudojamas versijas. Norėdami tai padaryti, turėtumėte perduoti papildomą parametrą „ApiVersion“ metodui, kaip parodyta toliau pateiktame kodo fragmente.

[„ApiVersion“ („1.0“, nebenaudojamas = tiesa)]

Susieti su konkrečia veiksmo metodo versija

Yra dar vienas svarbus atributas, pavadintas MapToApiVersion. Jį galite naudoti norėdami susieti su konkrečia veiksmo metodo versija. Šis kodo fragmentas parodo, kaip tai galima padaryti.

[„HttpGet“ („{id}“)]
[MapToApiVersion („2.0“)]
viešoji eilutė „Get“ (int id)
{
  grąžinti autorius [id];
}

Užbaigti API versijos pavyzdį ASP.NET Core

Čia yra visas jūsų numatytojo „DefaultController“ šaltinio kodas.

[Maršrutas („api / [valdiklis]“)]
[ApiController]
[ApiVersion („1.0“)]
[ApiVersion („1.1“)]
[ApiVersion („2.0“)]
viešoji klasė DefaultController: ControllerBase
{
  eilutė [] autoriai = nauja eilutė []
  {"Joydipas Kanjilalas", "Steve'as Smithas", "Stephenas Jonesas"};
  [HttpGet]
  public IEnumerable Get ()
  {
  grįžtantys autoriai;
  }
  [„HttpGet“ („{id}“)]
  [MapToApiVersion („2.0“)]
  viešoji eilutė „Get“ (int id)
  {
  grąžinti autorius [id];
  }
}

API versijų strategijos ASP.NET Core

Yra keli būdai, kuriais galite versijoti savo API sistemoje ASP.NET Core. Šiame skyriuje mes ištirsime kiekvieną iš jų.

Perduokite versijos informaciją kaip „QueryString“ parametrus

Tokiu atveju informaciją apie versiją paprastai perduodate kaip užklausos eilutės dalį, kaip parodyta toliau pateiktame URL.

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

Perduokite versijos informaciją HTTP antraštėse

Jei norite perduoti informaciją apie versiją HTTP antraštėse, turėtumėte ją nustatyti „ConfigureServices“ metodu, kaip parodyta toliau pateiktame kodo fragmente.

paslaugos.AddApiVersioning (config =>
{
  config.DefaultApiVersion = nauja ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = tiesa;
  config.ApiVersionReader = nauja HeaderApiVersionReader ("api versija");
});

Kai tai bus nustatyta, galite pasinaudoti veiksmo metodu, susijusiu su konkrečia API versija, kaip parodyta 3 paveiksle.

Perduokite versijos informaciją URL

Dar vienas informacijos apie versijas perdavimas yra informacijos apie versiją perdavimas kaip maršruto dalis. Tai yra paprasčiausias būdas versijuoti savo API, tačiau yra tam tikrų įspėjimų. Pirmiausia, jei naudojate šią strategiją, klientai turės atnaujinti URL, kai tik bus išleista nauja API versija. Taigi šis požiūris pažeidžia pagrindinį REST principą, kuris teigia, kad konkretaus ištekliaus URL niekada neturėtų keistis.

Norėdami įgyvendinti šią versijų strategiją, valdiklyje turėtumėte nurodyti maršruto informaciją, kaip parodyta žemiau.

[Maršrutas („api / v {versija: apiVersion} / [valdiklis]“)]

Šis kodų sąrašas parodo, kaip galite tai nustatyti savo valdiklio klasėje.

[Maršrutas („api / v {versija: apiVersion} / [valdiklis]“)]
[ApiController]
[ApiVersion („1.0“)]
[ApiVersion („1.1“)]
viešoji klasė DefaultController: ControllerBase
    {
  eilutė [] autoriai = nauja eilutė []
  {"Joydipas Kanjilalas", "Steve'as Smithas", "Stephenas Jonesas"};
  [HttpGet]
  public IEnumerable Get ()
        {
  grįžtantys autoriai;
        }
  [„HttpGet“ („{id}“)]
  [MapToApiVersion („2.0“)]
  viešoji eilutė „Get“ (int id)
        {
  grąžinti autorius [id];
        }
    }

Štai kaip galite iškviesti numatytąjį HTTP, kad gautumėte „DefaultController“ klasės metodą.

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

Norėdami iškviesti kitą HTTP GET metodą, t. Y. Tą, kuris priima parametrą, žiniatinklio naršyklėje arba HTTP kliente, pvz., „Postman“, nurodykite šiuos duomenis.

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

Nebenaudokite vienos ar daugiau API versijų

Tarkime, kad turite kelias savo API versijas, tačiau norėtumėte nebenaudoti vienos ar daugiau jų. Tai galite padaryti lengvai - jums tiesiog reikia nurodyti „ApiVersionAttribute“ klasės savybę „Panaikinta“ kaip „true“, kaip parodyta toliau pateiktame kodo fragmente.

[ApiController]
[ApiVersion („1.0“)]
[„ApiVersion“ („1.1“, nebenaudojamas = tiesa)]
[ApiVersion („2.0“)]
viešoji klasė DefaultController: ControllerBase
{
  // Įprastas kodas
}

ASP.NET Core versijos API versijos dabar yra sklandžios, nes įvedamas paketas „Microsoft.AspNetCore.Mvc.Versioning“. Yra keli API versijos versijos būdai - jums tereikia nuspręsti geriausią strategiją pagal jūsų reikalavimus. Savo API taip pat galite naudoti kelias versijų schemas. Tai suteikia daug lankstumo, nes klientai gali pasirinkti bet kurią iš palaikomų versijų schemų.