Kun kehität sovellusliittymiä, sinun on pidettävä mielessä yksi asia: Muutos on väistämätöntä. Kun sovellusliittymäsi on saavuttanut pisteen, jossa sinun on lisättävä lisää vastuita, sinun kannattaa harkita sovellusliittymän versiota. Siksi tarvitset versiostrategian.
Sovellusliittymien versiointiin on useita lähestymistapoja, ja jokaisella niistä on hyvät ja huonot puolensa. Tässä artikkelissa käsitellään API-versioiden haasteita ja sitä, miten voit työskennellä Microsoftin ASP.NET Core MVC Versioning -paketin ja ASP.NET Core -sovelluksen sisäisten RESTful-sovellusliittymien kanssa. Voit lukea lisää Web-sovellusliittymien versiosta edellisestä artikkelistani täältä.
Luo ASP.NET Core 3.1 -sovellusliittymäprojekti
Ensinnäkin, luodaan ASP.NET Core -projekti Visual Studiossa. Olettaen, että Visual Studio 2019 on asennettu järjestelmään, luo uusi ASP.NET Core -projekti Visual Studioon noudattamalla seuraavia ohjeita.
- Käynnistä Visual Studio IDE.
- Napsauta Luo uusi projekti.
- Valitse Luo uusi projekti -ikkunassa ”ASP.NET Core Web Application” näytetystä malliluettelosta.
- Napsauta Seuraava.
- Määritä seuraavan projektin nimi ja sijainti uuden Konfiguroi uusi projekti -ikkunassa.
- Napsauta Luo.
- Valitse Luo uusi ASP.NET-ydinverkkosovellus -ikkunassa .NET Core ajonaikaiseksi ja ASP.NET Core 3.1 (tai uudempi) yläreunan avattavasta luettelosta. Käytän täällä ASP.NET Core 3.1: tä.
- Luo uusi ASP.NET Core API -sovellus valitsemalla projektimalliksi “API”.
- Varmista, että valintaruudut Ota Docker-tuki käyttöön ja Määritä HTTPS: lle ei ole valittu, koska emme käytä näitä ominaisuuksia täällä.
- Varmista, että todennukseksi on määritetty Ei todentamista, koska emme myöskään käytä todennusta.
- Napsauta Luo.
Tämä luo uuden ASP.NET Core API -projektin Visual Studioon. Valitse Ohjainten ratkaisukansio Solution Explorer -ikkunassa ja napsauta “Lisää -> Ohjain…” luodaksesi uuden ohjaimen nimeltä DefaultController.
Korvaa DefaultController-luokan lähdekoodi seuraavalla koodilla.
[Reitti ("api / [ohjain]")] [ApiController]
public class DefaultController: ControllerBase
{
merkkijono [] kirjoittajat = uusi merkkijono []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
[HttpGet]
public IEnumerable Get ()
{
paluu kirjoittajat;
}
}
Käytämme tätä ohjainta tämän artikkelin seuraavissa osissa.
API-version käyttöönotto ASP.NET Core -sovelluksessa edellyttää seuraavaa:
- Asenna ASP.NET Core MVC Versioning -paketti.
- Määritä API-versiot Startup-luokassa.
- Merkitse ohjaimet ja toiminnot sopivilla määritteillä.
Asenna ASP.NET Core MVC Versioning -paketti
ASP.NET Core tarjoaa tuen API-versiolle valmiiksi. API-versioiden hyödyntämiseksi sinun tarvitsee vain asentaa Microsoft.AspNetCore.Mvc.Versioning -paketti NuGetistä. Voit tehdä tämän joko Visual Studio 2019 IDE: n sisällä olevan NuGet-paketinhallinnan kautta tai suorittamalla seuraavan komennon NuGet-paketinhallintakonsolissa:
Asennuspaketti Microsoft.AspNetCore.Mvc.Versioning
Huomaa, että jos käytät ASP.NET-Web-sovellusliittymää, sinun on lisättävä Microsoft.AspNet.WebApi.Versioning-paketti.
Määritä API-versiot ASP.NET Core -sovelluksessa
Nyt, kun tarvittava paketti sovellusliittymän versiointiin on asennettu projektiisi, voit määrittää sovellusliittymän version Startup-luokan ConfigureServices-menetelmällä. Seuraava koodinpätkä kuvaa, miten tämä voidaan saavuttaa.
public void ConfigureServices (IServiceCollection-palvelut){
palvelut.AddControllers ();
palvelut.AddApiVersioning ();
}
Kun teet hakupyynnön sovellusliittymällesi, sinulle näytetään kuvassa 1 esitetty virhe.
Voit korjata tämän virheen määrittämällä oletusversion, kun lisäät API-versiopalvelut säilöön. Voit myös haluta käyttää oletusversiota, jos versiota ei ole määritetty pyynnössä. Seuraava koodinpätkä näyttää, kuinka voit asettaa oletusversioksi 1.0 käyttämällä AssumeDefaultVersionWhenUnspecified-ominaisuutta, jos versiotiedot eivät ole käytettävissä pyynnössä.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = uusi ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
});
Huomaa, kuinka pääversio ja aliversio välitetään ApiVersion-luokan rakentajalle oletusversiota määritettäessä. Ominaisuus AssumeDefaultVersionWhenUnspecified voi sisältää joko tosi tai väärät arvot. Jos se on totta, käytetään API-versiota määritettäessä määritettyä oletusversiota, jos versiotietoja ei ole käytettävissä.
ConfigureServices-menetelmän täydellinen lähdekoodi on annettu alla viitteeksi.
public void ConfigureServices (IServiceCollection-palvelut){
palvelut.AddControllers ();
services.AddApiVersioning (config =>
{
config.DefaultApiVersion = uusi ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
});
}
Koska et ole määrittänyt versiotietoja, kaikilla päätepisteillä on oletusversio 1.0.
Ilmoita kaikista tuetuista versioista sovellusliittymästäsi
Haluat ehkä ilmoittaa sovellusliittymän asiakkaille kaikki tuetut versiot. Voit tehdä tämän hyödyntämällä ReportApiVersions-ominaisuutta alla olevan koodinpätkän mukaisesti.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = uusi ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
config.ReportApiVersions = tosi;
});
Käytä versioita ohjaimessa ja toimintamenetelmissä
Lisätään nyt muutama tuettu versio ohjaimeemme käyttämällä määritteitä, kuten alla olevassa koodinpätkässä on esitetty.
[Reitti ("api / [ohjain]")] [ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
public class DefaultController: ControllerBase
{
merkkijono [] kirjoittajat = uusi merkkijono []
{"Joydip Kanjilal", "Steve Smith", "Anand John"};
[HttpGet]
public IEnumerable Get ()
{
paluu kirjoittajat;
}
}
Kun teet Get-pyynnön HTTP-asiakkaalta, kuten Postman, versiot raportoidaan seuraavasti.
Voit ilmoittaa myös vanhentuneista versioista. Tätä varten sinun on välitettävä ylimääräinen parametri ApiVersion-menetelmälle alla olevan koodikatkelman mukaisesti.
[ApiVersion ("1.0", vanhentunut = tosi)]Yhdistä toimintamenetelmän tiettyyn versioon
On toinen tärkeä ominaisuus nimeltä MapToApiVersion. Voit käyttää sitä kartoittamaan toimintamenetelmän tiettyyn versioon. Seuraava koodinpätkä osoittaa, miten tämä voidaan saavuttaa.
[HttpGet ("{id}")][MapToApiVersion ("2.0")]
julkinen merkkijono Get (int id)
{
palauttavat kirjoittajat [id];
}
Täydellinen sovellusliittymän versionesitys ASP.NET Core -sovelluksessa
Tässä on DefaultControllerin täydellinen lähdekoodi viitteellesi.
[Reitti ("api / [ohjain]")][ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
public class DefaultController: ControllerBase
{
merkkijono [] kirjoittajat = uusi merkkijono []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
[HttpGet]
public IEnumerable Get ()
{
paluu kirjoittajat;
}
[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
julkinen merkkijono Get (int id)
{
palauttavat kirjoittajat [id];
}
}
API-versiostrategiat ASP.NET Core -sovelluksessa
ASP.NET Core -sovelluksessa on useita tapoja, joilla voit versiota sovellusliittymästäsi. Tässä osiossa tutkitaan niitä kaikkia.
Välitä versiotiedot QueryString-parametreina
Tässä tapauksessa lähetät tyypillisesti versiotiedot osana kyselymerkkijonoa alla olevan URL-osoitteen mukaisesti.
//localhost:25718/api/default?api-version=1.0
Välitä versiotiedot HTTP-otsikoihin
Jos haluat välittää versiotiedot HTTP-otsikoissa, määritä ne ConfigureServices-menetelmällä alla olevan koodinpätkän mukaisesti.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = uusi ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
config.ReportApiVersions = tosi;
config.ApiVersionReader = uusi HeaderApiVersionReader ("api-versio");
});
Kun tämä on määritetty, voit käyttää toimintomenetelmää, joka liittyy tiettyyn sovellusliittymän versioon, kuten kuvassa 3 on esitetty.
Välitä versiotiedot URL-osoitteeseen
Vielä yksi tapa välittää versiotiedot ovat versiotietojen välittäminen osana reittiä. Tämä on yksinkertaisin tapa versiota API: sta, mutta on olemassa tiettyjä varoituksia. Ensinnäkin, jos käytät tätä strategiaa, asiakkaidesi on päivitettävä URL-osoite aina, kun sovellusliittymän uusi versio julkaistaan. Näin ollen tämä lähestymistapa rikkoo REST-periaatteen, jonka mukaan tietyn resurssin URL-osoitteen ei pitäisi koskaan muuttua.
Tämän versiostrategian toteuttamiseksi sinun tulee määrittää reittitiedot ohjaimessa alla olevan kuvan mukaisesti.
[Reitti ("api / v {versio: apiVersion} / [ohjain]")]Seuraava koodiluettelo näyttää, kuinka voit asettaa tämän ohjainluokalle.
[Reitti ("api / v {versio: apiVersion} / [ohjain]")][ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
public class DefaultController: ControllerBase
{
merkkijono [] kirjoittajat = uusi merkkijono []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};
[HttpGet]
public IEnumerable Get ()
{
paluu kirjoittajat;
}
[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
julkinen merkkijono Get (int id)
{
palauttavat kirjoittajat [id];
}
}
Näin voit kutsua oletus-HTTP: n saadaksesi DefaultController-luokan menetelmän.
//localhost:25718/api/v1.0/default
Jos haluat kutsua toisen HTTP GET -menetelmän, so. Parametrin hyväksyvän menetelmän, määritä seuraava joko verkkoselaimessa tai HTTP-työasemassa, kuten Postman.
//localhost:25718/api/v2.0/default/1
Peruuta yksi tai useampi sovellusliittymän versio
Oletetaan, että sinulla on useita versioita sovellusliittymästäsi, mutta haluat hylätä yhden tai useamman niistä. Voit tehdä tämän helposti - sinun tarvitsee vain määrittää ApiVersionAttribute-luokan Poistettu-ominaisuus tosi-arvoksi, kuten alla olevassa koodinpätkässä näkyy.
[ApiController][ApiVersion ("1.0")]
[ApiVersion ("1.1", vanhentunut = tosi)]
[ApiVersion ("2.0")]
public class DefaultController: ControllerBase
{
// Tavallinen koodi
}
ASP.NET Core -sovelluksen sovellusliittymien versiointi on nyt saumatonta Microsoft.AspNetCore.Mvc.Versioning-paketin käyttöönoton ansiosta. API: n versiointiin on useita tapoja - sinun tarvitsee vain päättää paras strategia tarpeidesi mukaan. Voit käyttää myös useita versiomalleja API: llesi. Tämä lisää paljon joustavuutta, koska asiakkaat voivat valita minkä tahansa tuetuista versioista.
Kuinka tehdä enemmän ASP.NET Core -sovelluksessa:
- Kuinka käyttää tiedonsiirtoobjekteja ASP.NET Core 3.1: ssä
- Kuinka käsitellä 404 virhettä ASP.NET Core MVC: ssä
- Riippuvuusinjektion käyttäminen ASP.NET Core 3.1 -suodattimissa
- Asetuskuvion käyttäminen ASP.NET Core -sovelluksessa
- Kuinka käyttää päätepisteiden reititystä ASP.NET Core 3.0 MVC: ssä
- Tietojen vieminen Exceliin ASP.NET Core 3.0: ssa
- LoggerMessagen käyttäminen ASP.NET Core 3.0: ssa
- Kuinka lähettää sähköposteja ASP.NET Core -sovelluksessa
- Tietojen kirjaaminen SQL Server -palvelimeen ASP.NET Core -sovelluksessa
- Työn ajoitus Quartz.NET: n avulla ASP.NET Core -sovelluksessa
- Tietojen palauttaminen ASP.NET Core Web -sovellusliittymästä
- Kuinka muotoilla vastaustiedot ASP.NET Core -sovelluksessa
- ASP.NET Core Web -sovellusliittymän kuluttaminen RestSharpin avulla
- Asynkronointitoimintojen suorittaminen Dapperin avulla
- Ominaisuuslippujen käyttäminen ASP.NET Core -sovelluksessa
- FromServices-määritteen käyttäminen ASP.NET Core -sovelluksessa
- Kuinka toimia evästeiden kanssa ASP.NET Core -sovelluksessa
- Staattisten tiedostojen käsittely ASP.NET Core -sovelluksessa
- URL: n uudelleenkirjoittamisen väliohjelmiston käyttäminen ASP.NET Core -sovelluksessa
- Nopeudenrajoituksen toteuttaminen ASP.NET Core -sovelluksessa
- Kuinka käyttää Azure Application Insightsia ASP.NET Core -sovelluksessa
- NLog-lisäominaisuuksien käyttäminen ASP.NET Core -sovelluksessa
- Kuinka käsitellä virheitä ASP.NET Web API: ssa
- Kuinka toteuttaa maailmanlaajuinen poikkeusten käsittely ASP.NET Core MVC: ssä
- Kuinka käsitellä nolla-arvoja ASP.NET Core MVC: ssä
- Edistynyt versiointi ASP.NET Core Web -sovellusliittymässä
- Kuinka työskennellä työntekijöiden palveluiden kanssa ASP.NET Core -sovelluksessa
- Tietosuoja-sovellusliittymän käyttö ASP.NET Core -sovelluksessa
- Ehdollisen väliohjelmiston käyttäminen ASP.NET Core -sovelluksessa
- Istunnon tilan käyttäminen ASP.NET Core -sovelluksessa
- Kuinka kirjoittaa tehokkaita ohjaimia ASP.NET Core -sovellukseen
