Sådan bruges API-versionering i ASP.NET Core

Når du udvikler API'er, skal du huske en ting i tankerne: Ændring er uundgåelig. Når din API har nået et punkt, hvor du skal tilføje flere ansvarsområder, bør du overveje at versionere din API. Derfor har du brug for en versioneringsstrategi.

Der er flere tilgange til versionering af API'er, og hver af dem har sine fordele og ulemper. Denne artikel vil diskutere udfordringerne ved API-versionering og hvordan du kan arbejde med Microsofts ASP.NET Core MVC Versioning-pakke til version RESTful API'er indbygget i ASP.NET Core. Du kan læse mere om version af Web API i min tidligere artikel her.

Opret et ASP.NET Core 3.1 API-projekt

Lad os først starte med at oprette et ASP.NET Core-projekt i Visual Studio. Forudsat at Visual Studio 2019 er installeret i dit system, skal du følge trinene beskrevet nedenfor for at oprette et nyt ASP.NET Core-projekt i Visual Studio.

Start Visual Studio IDE.
Klik på "Opret nyt projekt."
I vinduet "Opret nyt projekt" skal du vælge "ASP.NET Core Web Application" fra listen over skabeloner, der vises.
Klik på Næste.
I vinduet "Konfigurer dit nye projekt", der vises nedenfor, skal du angive navnet og placeringen for det nye projekt.
Klik på Opret.
I vinduet "Opret ny ASP.NET Core-webapplikation" skal du vælge .NET Core som runtime og ASP.NET Core 3.1 (eller nyere) fra rullelisten øverst. Jeg bruger ASP.NET Core 3.1 her.
Vælg “API” som projektskabelon for at oprette en ny ASP.NET Core API-applikation.
Sørg for, at afkrydsningsfelterne "Aktivér Docker-support" og "Konfigurer til HTTPS" ikke er markeret, da vi ikke bruger disse funktioner her.
Sørg for, at godkendelse er indstillet som "Ingen godkendelse", da vi heller ikke bruger godkendelse.
Klik på Opret.

Dette opretter et nyt ASP.NET Core API-projekt i Visual Studio. Vælg Controllers-løsningsmappen i vinduet Solution Explorer, og klik på "Tilføj -> Controller ..." for at oprette en ny controller med navnet DefaultController.

Udskift kildekoden til klassen DefaultController 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 bruger denne controller i de efterfølgende afsnit i denne artikel.

For at implementere API-versionering i ASP.NET Core skal du gøre følgende:

Installer ASP.NET Core MVC Versioning-pakken.
Konfigurer API-versionering i opstartklassen.
Kommenter controllere og handlinger med passende attributter.

Installer pakken ASP.NET Core MVC Versioning

ASP.NET Core understøtter API-versionering out-of-the-box. For at udnytte API-versionering er alt, hvad du skal gøre, at installere Microsoft.AspNetCore.Mvc.Versioning-pakken fra NuGet. Du kan gøre dette enten via NuGet pakkehåndtering inde i Visual Studio 2019 IDE eller ved at udføre følgende kommando på NuGet pakkehåndteringskonsol:

Installationspakke Microsoft.AspNetCore.Mvc.Versioning

Bemærk, at hvis du bruger ASP.NET Web API, skal du tilføje pakken Microsoft.AspNet.WebApi.Versioning.

Konfigurer API-versionering i ASP.NET Core

Nu hvor den nødvendige pakke til versionering af din API er installeret i dit projekt, kan du konfigurere API-versionering i ConfigureServices-metoden i Startup-klassen. Følgende kodestykke illustrerer, hvordan dette kan opnås.

offentlig ugyldighed ConfigureServices (IServiceCollection-tjenester)
{
  services.AddControllers ();
  services.AddApiVersioning ();
}

Når du foretager en Get-anmodning til din API, får du vist fejlen vist i figur 1.

For at løse denne fejl kan du angive standardversionen, når du tilføjer API-versionstjenesterne til containeren. Du vil muligvis også bruge en standardversion, hvis en version ikke er angivet i anmodningen. Følgende kodestykke viser, hvordan du kan indstille en standardversion til 1.0 ved hjælp af egenskaben AssumeDefaultVersionWhenUnspecified, hvis versionoplysninger ikke er tilgængelige i anmodningen.

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

Bemærk, hvordan hovedversionen og den mindre version sendes til konstruktøren af ApiVersion-klassen på tidspunktet for tildelingen af standardversionen. Egenskaben AssumeDefaultVersionWhenUnspecified kan indeholde enten sande eller falske værdier. Hvis det er sandt, vil standardversionen, der er angivet ved konfiguration af API-versionering, blive brugt, hvis der ikke findes nogen versionoplysninger.

Den komplette kildekode for ConfigureServices-metoden er angivet nedenfor til din reference.

offentlig ugyldighed ConfigureServices (IServiceCollection-tjenester)
{
  services.AddControllers ();
  services.AddApiVersioning (config =>
    {
  config.DefaultApiVersion = ny ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
    });
}

Da du ikke har angivet nogen versionoplysninger, har alle slutpunkter standardversion 1.0.

Rapporter alle understøttede versioner af din API

Det kan være en god idé at lade API-klienterne kende alle understøttede versioner. For at gøre dette skal du udnytte egenskaben ReportApiVersions som vist i kodestykket nedenfor.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = ny ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = sandt;
});

Brug versioner i controlleren og handlingsmetoder

Lad os nu tilføje et par understøttede versioner til vores controller ved hjælp af attributter som vist i kodeuddraget 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 fremsætter en Get-anmodning fra en HTTP-klient som f.eks. Postman, skal du se, hvordan versionerne rapporteres.

Du kan også rapportere de forældede versioner. For at gøre dette skal du sende en ekstra parameter til ApiVersion-metoden som vist i kodestykket nedenfor.

[ApiVersion ("1.0", udfaset = sandt)]

Kort til en bestemt version af en handlingsmetode

Der er en anden vigtig attribut ved navn MapToApiVersion. Du kan bruge den til at kortlægge til en bestemt version af en handlingsmetode. Følgende kodestykke viser, hvordan dette kan opnås.

[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
public string Get (int id)
{
  returnere forfattere [id];
}

Komplet API-versioneringseksempel i ASP.NET Core

Her er den komplette kildekode til DefaultController til din reference.

[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")]
  public string Get (int id)
  {
  returnere forfattere [id];
  }
}

API-versioneringsstrategier i ASP.NET Core

Der er flere måder, hvorpå du kan versionere din API i ASP.NET Core. I dette afsnit undersøger vi hver af dem.

Pass versionoplysninger som QueryString-parametre

I dette tilfælde videregiver du typisk versionoplysningerne som en del af forespørgselsstrengen som vist i URL'en nedenfor.

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

Send versionoplysninger i HTTP-overskrifterne

Hvis du skal videregive versionoplysninger i HTTP-overskrifterne, skal du konfigurere dem i ConfigureServices-metoden som vist i kodestykket nedenfor.

services.AddApiVersioning (config =>
{
  config.DefaultApiVersion = ny ApiVersion (1, 0);
  config.AssumeDefaultVersionWhenUnspecified = true;
  config.ReportApiVersions = sandt;
  config.ApiVersionReader = ny HeaderApiVersionReader ("api-version");
});

Når dette er konfigureret, kan du påberåbe en handlingsmetode, der vedrører en bestemt version af API'en som vist i figur 3.

Send versionoplysninger i URL'en

Endnu en anden metode til at videregive versioninformation er at videregive versionoplysninger som en del af ruten. Dette er den enkleste måde at versionere din API på, men der er visse forbehold. Først og fremmest, hvis du bruger denne strategi, skal dine kunder opdatere URL'en, når en ny version af API frigives. Derfor bryder denne tilgang et grundlæggende princip i REST, der siger, at URL'en til en bestemt ressource aldrig skal ændres.

For at implementere denne versioneringsstrategi skal du angive ruteoplysningerne i din controller som vist nedenfor.

[Rute ("api / v {version: apiVersion} / [controller]")]

Følgende kodeliste viser, hvordan du kan konfigurere dette i din controller-klasse.

[Rute ("api / v {version: apiVersion} / [controller]")]
[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")]
  public string Get (int id)
        {
  returnere forfattere [id];
        }
    }

Her er hvordan du kan kalde standard HTTP for at få metoden til klassen DefaultController.

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

For at påkalde den anden HTTP GET-metode, dvs. den, der accepterer en parameter, skal du angive følgende enten i webbrowseren eller en HTTP-klient såsom Postman.

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

Foræld en eller flere versioner af din API

Antag, at du har flere versioner af din API, men du vil afskaffe en eller flere af dem. Du kan gøre dette let - du skal bare angive den udfasede egenskab for klassen ApiVersionAttribute til sand som vist i kodestykket nedenfor.

[ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1", udfaset = sand)]
[ApiVersion ("2.0")]
offentlig klasse DefaultController: ControllerBase
{
  // Almindelig kode
}

API-versionering i ASP.NET Core er nu problemfri takket være introduktionen af Microsoft.AspNetCore.Mvc.Versioning-pakken. Der er flere måder at versionere din API på - du skal bare beslutte den bedste strategi baseret på dine krav. Du kan også bruge flere versioneringsordninger til din API. Dette tilføjer en masse fleksibilitet, da klienterne kan vælge et hvilket som helst af de understøttede versioneringsordninger.