Verwendung der API-Versionierung in ASP.NET Core

Bei der Entwicklung von APIs sollten Sie eines berücksichtigen: Änderungen sind unvermeidlich. Wenn Ihre API einen Punkt erreicht hat, an dem Sie weitere Verantwortlichkeiten hinzufügen müssen, sollten Sie die Versionierung Ihrer API in Betracht ziehen. Daher benötigen Sie eine Versionierungsstrategie.

Es gibt verschiedene Ansätze zur Versionierung von APIs, von denen jeder seine Vor- und Nachteile hat. In diesem Artikel werden die Herausforderungen der API-Versionierung erläutert und wie Sie mit dem ASP.NET Core MVC-Versionspaket von Microsoft arbeiten können, um in ASP.NET Core integrierte RESTful-APIs zu versionieren. Weitere Informationen zur Web-API-Versionierung finden Sie in meinem vorherigen Artikel hier. 

Erstellen Sie ein ASP.NET Core 3.1-API-Projekt

Zunächst erstellen wir ein ASP.NET Core-Projekt in Visual Studio. Angenommen, Visual Studio 2019 ist auf Ihrem System installiert, führen Sie die folgenden Schritte aus, um ein neues ASP.NET Core-Projekt in Visual Studio zu erstellen.

  1. Starten Sie die Visual Studio-IDE.
  2. Klicken Sie auf "Neues Projekt erstellen".
  3. Wählen Sie im Fenster "Neues Projekt erstellen" aus der Liste der angezeigten Vorlagen "ASP.NET Core-Webanwendung" aus.
  4. Weiter klicken.
  5. Geben Sie im nächsten Fenster "Konfigurieren Sie Ihr neues Projekt" den Namen und den Speicherort für das neue Projekt an.
  6. Klicken Sie auf Erstellen.
  7. Wählen Sie im Fenster "Neue ASP.NET Core-Webanwendung erstellen" .NET Core als Laufzeit und ASP.NET Core 3.1 (oder höher) aus der Dropdown-Liste oben aus. Ich werde hier ASP.NET Core 3.1 verwenden.
  8. Wählen Sie "API" als Projektvorlage aus, um eine neue ASP.NET Core API-Anwendung zu erstellen. 
  9. Stellen Sie sicher, dass die Kontrollkästchen "Docker-Unterstützung aktivieren" und "Für HTTPS konfigurieren" deaktiviert sind, da diese Funktionen hier nicht verwendet werden.
  10. Stellen Sie sicher, dass die Authentifizierung auf "Keine Authentifizierung" eingestellt ist, da wir auch keine Authentifizierung verwenden.
  11. Klicken Sie auf Erstellen. 

Dadurch wird ein neues ASP.NET Core API-Projekt in Visual Studio erstellt. Wählen Sie im Projektmappen-Explorer den Lösungsordner "Controller" aus und klicken Sie auf "Hinzufügen -> Controller ...", um einen neuen Controller mit dem Namen "DefaultController" zu erstellen.

Ersetzen Sie den Quellcode der DefaultController-Klasse durch den folgenden Code.

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

    [ApiController]

    öffentliche Klasse DefaultController: ControllerBase

    {

        Zeichenfolge [] Autoren = neue Zeichenfolge []

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

        [HttpGet]

        public IEnumerable Get ()

        {

            Autoren zurückgeben;

        }}

    }}

Wir werden diesen Controller in den folgenden Abschnitten dieses Artikels verwenden.

Um die API-Versionierung in ASP.NET Core zu implementieren, müssen Sie folgende Schritte ausführen:

  1. Installieren Sie das ASP.NET Core MVC-Versionspaket.
  2. Konfigurieren Sie die API-Versionierung in der Startup-Klasse.
  3. Kommentieren Sie die Controller und Aktionen mit den entsprechenden Attributen.

Installieren Sie das ASP.NET Core MVC-Versionspaket

ASP.NET Core bietet Unterstützung für die sofort einsatzbereite API-Versionierung. Um die API-Versionierung zu nutzen, müssen Sie lediglich das Microsoft.AspNetCore.Mvc.Versioning-Paket von NuGet installieren. Sie können dies entweder über den NuGet-Paketmanager in der Visual Studio 2019-IDE oder durch Ausführen des folgenden Befehls in der NuGet-Paketmanagerkonsole tun:

Installationspaket Microsoft.AspNetCore.Mvc.Versioning

Beachten Sie, dass Sie bei Verwendung der ASP.NET-Web-API das Paket Microsoft.AspNet.WebApi.Versioning hinzufügen sollten.

Konfigurieren Sie die API-Versionierung in ASP.NET Core

Nachdem das für die Versionierung Ihrer API erforderliche Paket in Ihrem Projekt installiert wurde, können Sie die API-Versionierung in der ConfigureServices-Methode der Startup-Klasse konfigurieren. Das folgende Codefragment zeigt, wie dies erreicht werden kann.

public void ConfigureServices (IServiceCollection-Dienste)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}}

Wenn Sie eine Get-Anfrage an Ihre API stellen, wird der in Abbildung 1 gezeigte Fehler angezeigt.

Um diesen Fehler zu beheben, können Sie die Standardversion angeben, wenn Sie die API-Versionierungsdienste zum Container hinzufügen. Möglicherweise möchten Sie auch eine Standardversion verwenden, wenn in der Anforderung keine Version angegeben ist. Das folgende Codefragment zeigt, wie Sie mit der AssumeDefaultVersionWhenUnspecified-Eigenschaft eine Standardversion als 1.0 festlegen können, wenn in der Anforderung keine Versionsinformationen verfügbar sind.

services.AddApiVersioning (config =>

{

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

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Beachten Sie, wie die Hauptversion und die Nebenversion zum Zeitpunkt der Zuweisung der Standardversion an den Konstruktor der ApiVersion-Klasse übergeben werden. Die Eigenschaft AssumeDefaultVersionWhenUnspecified kann entweder wahre oder falsche Werte enthalten. Wenn dies der Fall ist, wird die bei der Konfiguration der API-Versionierung angegebene Standardversion verwendet, wenn keine Versionsinformationen verfügbar sind.

Der vollständige Quellcode der ConfigureServices-Methode wird unten als Referenz angegeben.

public void ConfigureServices (IServiceCollection-Dienste)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

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

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}}

Da Sie keine Versionsinformationen angegeben haben, haben alle Endpunkte die Standardversion 1.0.

Melden Sie alle unterstützten Versionen Ihrer API

Möglicherweise möchten Sie den Clients der API alle unterstützten Versionen mitteilen. Zu diesem Zweck sollten Sie die ReportApiVersions-Eigenschaft nutzen, wie im folgenden Code-Snippet gezeigt.

services.AddApiVersioning (config =>

{

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

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

Verwenden Sie Versionen in der Controller- und Aktionsmethode

Fügen wir unserem Controller nun einige unterstützte Versionen hinzu, indem wir Attribute verwenden, wie im folgenden Code-Snippet gezeigt.

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

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    öffentliche Klasse DefaultController: ControllerBase

    {

        Zeichenfolge [] Autoren = neue Zeichenfolge []

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

        [HttpGet]

        public IEnumerable Get ()

        {

            Autoren zurückgeben;

        }}

    }}

Wenn Sie eine Get-Anfrage von einem HTTP-Client wie Postman stellen, werden die Versionen wie folgt gemeldet.

Sie können auch die veralteten Versionen melden. Zu diesem Zweck sollten Sie der ApiVersion-Methode einen zusätzlichen Parameter übergeben, wie im folgenden Code-Snippet gezeigt.

[ApiVersion ("1.0", veraltet = wahr)]

Zuordnung zu einer bestimmten Version einer Aktionsmethode

Es gibt ein weiteres wichtiges Attribut namens MapToApiVersion. Sie können es verwenden, um einer bestimmten Version einer Aktionsmethode zuzuordnen. Das folgende Codefragment zeigt, wie dies erreicht werden kann.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

public string Get (int id)

{

   Autoren zurückgeben [id];

}}

Vollständiges API-Versionsbeispiel in ASP.NET Core

Hier finden Sie den vollständigen Quellcode des DefaultControllers als Referenz.

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

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

öffentliche Klasse DefaultController: ControllerBase

{

  Zeichenfolge [] Autoren = neue Zeichenfolge []

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

  [HttpGet]

  public IEnumerable Get ()

  {

      Autoren zurückgeben;

  }}

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  public string Get (int id)

  {

     Autoren zurückgeben [id];

  }}

}}

API-Versionierungsstrategien in ASP.NET Core

Es gibt verschiedene Möglichkeiten, wie Sie Ihre API in ASP.NET Core versionieren können. In diesem Abschnitt werden wir jeden von ihnen untersuchen.

Übergeben Sie Versionsinformationen als QueryString-Parameter

In diesem Fall übergeben Sie normalerweise die Versionsinformationen als Teil der Abfragezeichenfolge, wie in der unten angegebenen URL angegeben.

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

Übergeben Sie Versionsinformationen in den HTTP-Headern

Wenn Sie Versionsinformationen in den HTTP-Headern übergeben möchten, sollten Sie diese in der ConfigureServices-Methode einrichten, wie im folgenden Codeausschnitt gezeigt.

services.AddApiVersioning (config =>

{

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

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = neuer HeaderApiVersionReader ("API-Version");

});

Sobald dies eingerichtet wurde, können Sie eine Aktionsmethode aufrufen, die sich auf eine bestimmte Version der API bezieht (siehe Abbildung 3).

Übergeben Sie Versionsinformationen in die URL

Eine weitere Methode zum Übergeben von Versionsinformationen ist das Übergeben von Versionsinformationen als Teil der Route. Dies ist die einfachste Methode zur Versionierung Ihrer API, es gibt jedoch bestimmte Einschränkungen. Wenn Sie diese Strategie verwenden, müssen Ihre Clients zunächst die URL aktualisieren, wenn eine neue Version der API veröffentlicht wird. Folglich verstößt dieser Ansatz gegen ein grundlegendes Prinzip von REST, das besagt, dass sich die URL einer bestimmten Ressource niemals ändern sollte.

Um diese Versionsstrategie zu implementieren, sollten Sie die Routeninformationen in Ihrem Controller wie unten gezeigt angeben.

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

Die folgende Codeliste zeigt, wie Sie dies in Ihrer Controller-Klasse einrichten können.

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

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

öffentliche Klasse DefaultController: ControllerBase

    {

        Zeichenfolge [] Autoren = neue Zeichenfolge []

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

        [HttpGet]

        public IEnumerable Get ()

        {

            Autoren zurückgeben;

        }}

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        public string Get (int id)

        {

            Autoren zurückgeben [id];

        }}

    }}

So können Sie das Standard-HTTP aufrufen, um die Methode der DefaultController-Klasse abzurufen.

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

Um die andere HTTP-GET-Methode aufzurufen, dh die, die einen Parameter akzeptiert, geben Sie Folgendes entweder im Webbrowser oder in einem HTTP-Client wie Postman an.

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

Veralten Sie eine oder mehrere Versionen Ihrer API

Angenommen, Sie haben mehrere Versionen Ihrer API, möchten jedoch eine oder mehrere davon ablehnen. Sie können dies einfach tun - Sie müssen nur die veraltete Eigenschaft der ApiVersionAttribute-Klasse auf true angeben, wie im unten angegebenen Code-Snippet gezeigt.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", veraltet = wahr)]

[ApiVersion ("2.0")]

öffentliche Klasse DefaultController: ControllerBase

{

     // Üblicher Code

}}

Dank der Einführung des Microsoft.AspNetCore.Mvc.Versioning-Pakets ist die API-Versionierung in ASP.NET Core jetzt nahtlos. Es gibt verschiedene Möglichkeiten, Ihre API zu versionieren: Sie müssen lediglich die beste Strategie basierend auf Ihren Anforderungen festlegen. Sie können auch mehrere Versionsschemata für Ihre API verwenden. Dies erhöht die Flexibilität, da die Clients eines der unterstützten Versionsschemata auswählen können.

So machen Sie mehr in ASP.NET Core:

  • Verwendung von Datenübertragungsobjekten in ASP.NET Core 3.1
  • Behandlung von 404-Fehlern in ASP.NET Core MVC
  • Verwendung der Abhängigkeitsinjektion in Aktionsfiltern in ASP.NET Core 3.1
  • Verwendung des Optionsmusters in ASP.NET Core
  • Verwendung des Endpunktroutings in ASP.NET Core 3.0 MVC
  • Exportieren von Daten nach Excel in ASP.NET Core 3.0
  • Verwendung von LoggerMessage in ASP.NET Core 3.0
  • So senden Sie E-Mails in ASP.NET Core
  • So protokollieren Sie Daten in SQL Server in ASP.NET Core
  • So planen Sie Jobs mit Quartz.NET in ASP.NET Core
  • So geben Sie Daten von der ASP.NET Core Web API zurück
  • So formatieren Sie Antwortdaten in ASP.NET Core
  • So verwenden Sie eine ASP.NET Core-Web-API mit RestSharp
  • So führen Sie asynchrone Vorgänge mit Dapper aus
  • Verwendung von Feature-Flags in ASP.NET Core
  • Verwendung des FromServices-Attributs in ASP.NET Core
  • So arbeiten Sie mit Cookies in ASP.NET Core
  • So arbeiten Sie mit statischen Dateien in ASP.NET Core
  • Verwendung der URL-Rewriting-Middleware in ASP.NET Core
  • Implementieren der Ratenbegrenzung in ASP.NET Core
  • So verwenden Sie Azure Application Insights in ASP.NET Core
  • Verwenden erweiterter NLog-Funktionen in ASP.NET Core
  • Behandlung von Fehlern in der ASP.NET-Web-API
  • Implementieren der globalen Ausnahmebehandlung in ASP.NET Core MVC
  • Umgang mit Nullwerten in ASP.NET Core MVC
  • Erweiterte Versionierung in der ASP.NET Core-Web-API
  • So arbeiten Sie mit Worker Services in ASP.NET Core
  • Verwendung der Datenschutz-API in ASP.NET Core
  • Verwendung der bedingten Middleware in ASP.NET Core
  • So arbeiten Sie mit dem Sitzungsstatus in ASP.NET Core
  • So schreiben Sie effiziente Controller in ASP.NET Core