Programmering

Hvordan bruke API-versjonering i ASP.NET Core

Når du utvikler API-er, bør du huske en ting i tankene: Endring er uunngåelig. Når API-en din har nådd et punkt der du trenger å legge til mer ansvar, bør du vurdere å versjonere API-en din. Derfor trenger du en versjonsstrategi.

Det er flere tilnærminger til versjon av APIer, og hver av dem har sine fordeler og ulemper. Denne artikkelen vil diskutere utfordringene ved API-versjonering og hvordan du kan jobbe med Microsofts ASP.NET Core MVC Versjonspakke til versjon RESTful APIer innebygd i ASP.NET Core. Du kan lese mer om Web API-versjon i min forrige artikkel her.

Opprett et ASP.NET Core 3.1 API-prosjekt

Først og fremst, la oss lage et ASP.NET Core-prosjekt i Visual Studio. Forutsatt at Visual Studio 2019 er installert i systemet ditt, følger du trinnene som er beskrevet nedenfor for å opprette et nytt ASP.NET Core-prosjekt i Visual Studio.

  1. Start Visual Studio IDE.
  2. Klikk på "Opprett nytt prosjekt."
  3. I vinduet "Opprett nytt prosjekt" velger du "ASP.NET Core Web Application" fra listen over maler som vises.
  4. Klikk på Neste.
  5. I vinduet “Konfigurer ditt nye prosjekt” som vises, angir du navnet og stedet for det nye prosjektet.
  6. Klikk på Opprett.
  7. I vinduet "Create New ASP.NET Core Web Application" velger du .NET Core som kjøretid og ASP.NET Core 3.1 (eller nyere) fra rullegardinlisten øverst. Jeg bruker ASP.NET Core 3.1 her.
  8. Velg “API” som prosjektmal for å opprette et nytt ASP.NET Core API-program.
  9. Forsikre deg om at avmerkingsboksene "Aktiver Docker-støtte" og "Konfigurer for HTTPS" ikke er merket av da vi ikke bruker disse funksjonene her.
  10. Forsikre deg om at autentisering er angitt som “ingen godkjenning”, da vi heller ikke bruker autentisering.
  11. Klikk på Opprett.

Dette vil opprette et nytt ASP.NET Core API-prosjekt i Visual Studio. Velg Controllers-løsningsmappen i Solution Explorer-vinduet, og klikk "Legg til -> Controller ..." for å opprette en ny kontroller som heter DefaultController.

Erstatt kildekoden til StandardController-klassen med følgende kode.

  [Rute ("api / [controller]")]

[ApiController]

offentlig klasse DefaultController: ControllerBase

    {

streng [] forfattere = ny streng []

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

[HttpGet]

offentlig IEnumerable Get ()

        {

returnere forfattere;

        }

    }

Vi bruker denne kontrolleren i de påfølgende delene av denne artikkelen.

For å implementere API-versjonering i ASP.NET Core må du gjøre følgende:

  1. Installer ASP.NET Core MVC Versjonspakken.
  2. Konfigurer API-versjonering i Startup-klassen.
  3. Kommenter kontrollerne og handlingene med passende attributter.

Installer ASP.NET Core MVC Versjonspakken

ASP.NET Core gir støtte for API-versjonering utenom boksen. For å utnytte API-versjonering er alt du trenger å gjøre å installere Microsoft.AspNetCore.Mvc.Versioning-pakken fra NuGet. Du kan gjøre dette enten via NuGet pakkebehandling i Visual Studio 2019 IDE, eller ved å utføre følgende kommando på NuGet pakkebehandler-konsoll:

Installasjonspakke Microsoft.AspNetCore.Mvc.Versioning

Vær oppmerksom på at hvis du bruker ASP.NET Web API, bør du legge til Microsoft.AspNet.WebApi.Versioning-pakken.

Konfigurer API-versjonering i ASP.NET Core

Nå som den nødvendige pakken for versjonering av API-en din er installert i prosjektet ditt, kan du konfigurere API-versjonering i ConfigureServices-metoden i oppstartsklassen. Følgende kodebit illustrerer hvordan dette kan oppnås.

offentlig ugyldighet ConfigureServices (IServiceCollection-tjenester)

{

tjenester.AddControllers ();

services.AddApiVersioning ();

}

Når du lager en Get-forespørsel til API-en din, vil du bli presentert for feilen vist i figur 1.

For å løse denne feilen kan du angi standardversjonen når du legger til API-versjonstjenestene i containeren. Det kan også være lurt å bruke en standardversjon hvis en versjon ikke er spesifisert i forespørselen. Følgende kodebit viser hvordan du kan angi en standardversjon som 1.0 ved hjelp av AssumeDefaultVersionWhenUnspecified-egenskapen hvis versjonsinformasjon ikke er tilgjengelig i forespørselen.

services.AddApiVersioning (config =>

{

config.DefaultApiVersion = ny ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

});

Legg merke til hvordan hovedversjonen og mindreversjonen sendes til konstruktøren av ApiVersion-klassen på tidspunktet for tildeling av standardversjonen. Eiendommen AssumeDefaultVersionWhenUnspecified kan inneholde enten sanne eller falske verdier. Hvis det er sant, vil standardversjonen som er spesifisert når du konfigurerer API-versjonering, brukes hvis ingen versjonsinformasjon er tilgjengelig.

Den komplette kildekoden til ConfigureServices-metoden er gitt nedenfor for din referanse.

offentlig ugyldighet ConfigureServices (IServiceCollection-tjenester)

{

tjenester.AddControllers ();

services.AddApiVersioning (config =>

    {

config.DefaultApiVersion = ny ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Siden du ikke har spesifisert noen versjonsinformasjon, vil alle sluttpunkter ha standardversjonen 1.0.

Rapporter alle støttede versjoner av API-et

Det kan være lurt å fortelle kundene til API-et om alle versjoner som støttes. For å gjøre dette, bør du dra nytte av ReportApiVersions-egenskapen som vist i kodebiten gitt nedenfor.

services.AddApiVersioning (config =>

{

config.DefaultApiVersion = ny ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

config.ReportApiVersions = true;

});

Bruk versjoner i kontrolleren og handlingsmetoder

La oss nå legge til noen støttede versjoner til kontrolleren vår ved hjelp av attributter som vist i kodebiten gitt nedenfor.

  [Rute ("api / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

offentlig klasse DefaultController: ControllerBase

    {

streng [] forfattere = ny streng []

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

[HttpGet]

offentlig IEnumerable Get ()

        {

returnere forfattere;

        }

    }

Når du lager en Get-forespørsel fra en HTTP-klient som Postman, kan du se hvordan versjonene blir rapportert.

Du kan også rapportere de utdaterte versjonene. For å gjøre dette, bør du sende en ekstra parameter til ApiVersion-metoden som vist i kodebiten gitt nedenfor.

[ApiVersion ("1.0", utdatert = sann)]

Kartlegg til en bestemt versjon av en handlingsmetode

Det er en annen viktig egenskap som heter MapToApiVersion. Du kan bruke den til å kartlegge til en bestemt versjon av en handlingsmetode. Følgende kodebit viser hvordan dette kan oppnås.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

offentlig streng Get (int id)

{

returnere forfattere [id];

}

Komplett API-versjonseksempel i ASP.NET Core

Her er den komplette kildekoden til DefaultController som referanse.

[Rute ("api / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

offentlig klasse DefaultController: ControllerBase

{

streng [] forfattere = ny streng []

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

[HttpGet]

offentlig IEnumerable Get ()

  {

returnere forfattere;

  }

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

offentlig streng Get (int id)

  {

returnere forfattere [id];

  }

}

API-versjonsstrategier i ASP.NET Core

Det er flere måter du kan versjonere API på i ASP.NET Core. I denne delen vil vi utforske hver av dem.

Gi versjonsinformasjon som QueryString-parametere

I dette tilfellet sender du vanligvis versjonsinformasjonen som en del av spørringsstrengen som vist i URL-en gitt nedenfor.

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

Send versjonsinformasjon i HTTP-overskriftene

Hvis du skal sende versjonsinformasjon i HTTP-overskriftene, bør du sette den opp i ConfigureServices-metoden som vist i kodebiten gitt nedenfor.

services.AddApiVersioning (config =>

{

config.DefaultApiVersion = ny ApiVersion (1, 0);

config.AssumeDefaultVersionWhenUnspecified = true;

config.ReportApiVersions = true;

config.ApiVersionReader = ny HeaderApiVersionReader ("api-versjon");

});

Når dette er konfigurert, kan du påkalle en handlingsmetode som gjelder en bestemt versjon av API som vist i figur 3.

Send versjonsinformasjon i URL-en

Nok en annen metode for å sende versjonsinformasjon er å sende versjonsinformasjon som en del av ruten. Dette er den enkleste måten å versjonere API-en på, men det er visse advarsler. Først og fremst, hvis du bruker denne strategien, må kundene dine oppdatere URL-en når en ny versjon av API-en blir gitt ut. Følgelig bryter denne tilnærmingen et grunnleggende prinsipp for REST som sier at URL-en til en bestemt ressurs aldri skal endres.

For å implementere denne versjonsstrategien, bør du spesifisere ruteinformasjonen i kontrolleren din som vist nedenfor.

[Rute ("api / v {versjon: apiVersion} / [kontroller]")]

Følgende kodeliste viser hvordan du kan sette opp dette i kontrollerklassen din.

[Rute ("api / v {versjon: apiVersion} / [kontroller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

offentlig klasse DefaultController: ControllerBase

    {

streng [] forfattere = ny streng []

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

[HttpGet]

offentlig IEnumerable Get ()

        {

returnere forfattere;

        }

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

offentlig streng Get (int id)

        {

returnere forfattere [id];

        }

    }

Slik kan du ringe standard HTTP for å få metoden i klassen DefaultController.

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

For å påkalle den andre HTTP GET-metoden, dvs. den som godtar en parameter, angir du følgende enten i nettleseren eller en HTTP-klient som Postman.

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

Avvikle en eller flere versjoner av API-et

Anta at du har flere versjoner av API-et ditt, men du vil avskrive en eller flere av dem. Du kan gjøre dette enkelt - du trenger bare å spesifisere den utfasede egenskapen til ApiVersionAttribute-klassen til true som vist i kodebiten gitt nedenfor.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", utdatert = sann)]

[ApiVersion ("2.0")]

offentlig klasse DefaultController: ControllerBase

{

// Vanlig kode

}

API-versjonering i ASP.NET Core er nå sømløs takket være introduksjonen av Microsoft.AspNetCore.Mvc.Versioning-pakken. Det er flere måter å versjonere API på - du trenger bare å bestemme den beste strategien basert på dine krav. Du kan også bruke flere versjonsskjemaer for API-en. Dette gir mye fleksibilitet siden kundene kan velge hvilken som helst versjonsordning som støttes.

Hvordan gjøre mer i ASP.NET Core:

  • Hvordan bruke dataoverføringsobjekter i ASP.NET Core 3.1
  • Hvordan håndtere 404 feil i ASP.NET Core MVC
  • Hvordan bruke avhengighetsinjeksjon i handlingsfiltre i ASP.NET Core 3.1
  • Hvordan bruke alternativmønsteret i ASP.NET Core
  • Hvordan bruke endepunktsruting i ASP.NET Core 3.0 MVC
  • Slik eksporterer du data til Excel i ASP.NET Core 3.0
  • Hvordan bruke LoggerMessage i ASP.NET Core 3.0
  • Hvordan sende e-post i ASP.NET Core
  • Hvordan logge data til SQL Server i ASP.NET Core
  • Hvordan planlegge jobber med Quartz.NET i ASP.NET Core
  • Hvordan returnere data fra ASP.NET Core Web API
  • Hvordan formatere svardata i ASP.NET Core
  • Slik bruker du et ASP.NET Core Web API ved hjelp av RestSharp
  • Hvordan utføre asynkroniseringsoperasjoner ved hjelp av Dapper
  • Hvordan bruke funksjonsflagg i ASP.NET Core
  • Hvordan bruke attributtet FromServices i ASP.NET Core
  • Hvordan jobbe med informasjonskapsler i ASP.NET Core
  • Hvordan jobbe med statiske filer i ASP.NET Core
  • Hvordan bruke URL Rewriting Middleware i ASP.NET Core
  • Hvordan implementere hastighetsbegrensning i ASP.NET Core
  • Hvordan bruke Azure Application Insights i ASP.NET Core
  • Bruker avanserte NLog-funksjoner i ASP.NET Core
  • Hvordan håndtere feil i ASP.NET Web API
  • Hvordan implementere global unntaksbehandling i ASP.NET Core MVC
  • Hvordan håndtere nullverdier i ASP.NET Core MVC
  • Avansert versjonering i ASP.NET Core Web API
  • Hvordan jobbe med arbeidstjenester i ASP.NET Core
  • Hvordan bruke API for databeskyttelse i ASP.NET Core
  • Hvordan bruke betinget mellomvare i ASP.NET Core
  • Hvordan jobbe med økttilstand i ASP.NET Core
  • Hvordan skrive effektive kontrollere i ASP.NET Core
$config[zx-auto] not found$config[zx-overlay] not found