Migration von ASP.NET Web API zu ASP.NET Core mit HTTP-Vertrag

ASP.NET Web API zu ASP.NET Core: Warum eine Portierung, die kompiliert, trotzdem jeden Client brechen kann

Teams, die einen Dienst von ASP.NET Web API 2 nach ASP.NET Core umziehen wollen, sorgen sich meist um den Code: Controller, Filter, Dependency Injection, Entity Framework. Diese Teile kosten Zeit, verursachen aber selten die Störungen. Die Störungen entstehen bei dem, was die Clients sehen: ein Eigenschaftsname mit anderem Anfangsbuchstaben, ein 404, das plötzlich einen Inhalt hat, eine Fehlermeldung in neuem Format.

Dieser Artikel zeigt das Problem an einem echten, öffentlichen Beispiel und beschreibt die Methode, mit der wir es in unseren Projekten zur Migration von ASP.NET Web API zu ASP.NET Core verhindern. Wenn Sie noch über die Zielplattform selbst nachdenken, finden Sie in einem früheren Artikel fünf Gründe für ASP.NET Core.

Warum diese Migration eine Portierung und kein Upgrade ist

ASP.NET Web API 2 baut auf System.Web und OWIN auf. Beides gibt es in modernem .NET nicht. Es existiert also kein Versionsschalter, der ein Web-API-2-Projekt auf .NET 10 hebt. Die Webschicht wird durch ASP.NET Core ersetzt: Controller oder Minimal APIs, Middleware statt Message Handler, integrierte Dependency Injection, eine andere JSON-Bibliothek.

Geschäftslogik und Datenzugriff ziehen oft mit geringen Änderungen um. Was sich ändert, ohne dass jemand es entscheidet, sind die Standardeinstellungen des neuen Frameworks. Eine Controller-Methode, die in beiden Versionen dasselbe Objekt zurückgibt, erzeugt nicht zwangsläufig dieselbe HTTP-Antwort.

Der typische Fehler: die Portierung am Code beurteilen

Üblicherweise prüft man einen portierten Dienst, indem man den Code liest, die Unit-Tests ausführt und einige Endpunkte von Hand aufruft. Alle drei Prüfungen können gut aussehen, während die API für ihre Clients kaputt ist, denn keine davon vergleicht die Antwort Byte für Byte mit dem, was der alte Dienst geliefert hat.

Eine vor zwei Jahren veröffentlichte Mobile-App, eine Partnerintegration, ein Reporting-Skript: Nichts davon wird am Tag der Umschaltung aktualisiert. Für diese Clients ist die API nicht der Code, sondern die exakte Form der Antworten.

Das Beispiel: ein Vertrag, zwei Implementierungen

Um das messbar zu machen, haben wir eine kleine Bestell-API so gebaut, wie viele interne .NET-Framework-Dienste geschrieben wurden: .NET Framework 4.8, Web API 2 auf OWIN, Entity Framework 6 mit Lazy Loading, Json.NET, ein statischer Service Locator. Anschließend haben wir sie auf .NET 10 mit ASP.NET-Core-Controllern, EF Core und System.Text.Json migriert. Beide Versionen liegen in Fall 01 unseres GitHub-Repositorys, eine Beschreibung finden Sie auf legacy-modernisierung.de.

Bevor Code umgezogen ist, wurde das Verhalten der alten API als Daten festgehalten: 17 HTTP-Fälle, jeweils mit Anfrage, erwartetem Statuscode und erwartetem Inhalt. Eigenschaftsnamen werden unter Beachtung der Groß- und Kleinschreibung verglichen. Die alte Testsuite führt diese Datei gegen Web API 2 aus, die migrierte Suite dieselbe Datei gegen ASP.NET Core. Nichts in der Datei weiß, welches Framework antwortet.

Die erste Portierung der Controller ließ sich kompilieren und sah richtig aus. Das sagte der Vertrag dazu:

Schritt Bestandene Fälle Was falsch war
Direkte Portierung mit Framework-Standards 0 von 17 Jede Antwort verwendete Eigenschaftsnamen in camelCase
Eigenschaftsnamen wie deklariert 14 von 17 Drei Abweichungen blieben, siehe unten
Kompatibilitätseinstellungen 17 von 17 Nichts

Eigenschaftsnamen: 0 von 17

Web API 2 mit Json.NET schreibt Eigenschaftsnamen so, wie sie in C# deklariert sind, zum Beispiel Id und CustomerName. ASP.NET Core mit System.Text.Json schreibt standardmäßig id und customerName. Einem JavaScript-Client fällt das womöglich nicht auf. Bei einem Client, der in ein typisiertes Modell mit exakten Namen deserialisiert, ist plötzlich jedes Feld leer. Eine Konfigurationszeile behebt das – aber nur, wenn es jemand vor dem Release bemerkt.

Ein 404 mit Inhalt

Die alte API beantwortete eine unbekannte Bestellung mit Status 404 und leerem Inhalt. In einem ASP.NET-Core-Controller mit dem API-Controller-Attribut liefert derselbe Aufruf eine Problembeschreibung als JSON. Der Statuscode ist derselbe, ein schneller manueller Test besteht also. Ein Client, der jeden Inhalt als auszuwertende Nutzdaten behandelt, besteht ihn nicht.

Ungültiges JSON erreichte die Action nicht mehr

Schickte ein Client einen fehlerhaften Inhalt, lief in der alten API die Action und gab ihre eigene Fehlermeldung zurück. ASP.NET Core beantwortet eine solche Anfrage selbst, noch bevor die Action aufgerufen wird, mit einer Validierungsantwort in einem anderen Format. Clients, die das alte Meldungsfeld anzeigen oder protokollieren, bekommen nichts.

Fehler aus der Middleware

Die Prüfung des API-Schlüssels ist von einem Message Handler in eine Middleware gewandert. Antworten aus der Middleware nutzen andere JSON-Optionen als Controller. Die Namenskorrektur für Controller griff dort nicht, und genau dieser eine Fehler kam in camelCase zurück. Ein gutes Beispiel für eine Abweichung, nach der niemand suchen würde.

Alle drei Punkte sind im Startcode des migrierten Dienstes behoben, jeweils mit einem Kommentar, welches alte Verhalten damit erhalten bleibt.

Was nicht kaputtging, obwohl es oft kaputtgeht

Ein Vertrag hilft auch bei Befürchtungen, die sich als unbegründet erweisen. Im Beispiel bestanden diese Fälle ohne jede Änderung:

  • Zahlen als Zeichenfolgen. Alte Clients senden eine Menge in Anführungszeichen. Json.NET akzeptiert das, und System.Text.Json mit den Web-Standards von ASP.NET Core ebenfalls.
  • Eigenschaftsnamen in Anfragen mit anderer Schreibweise. Aus demselben Grund akzeptiert.
  • Geldbeträge. Summen werden im Fachcode mit einer ausdrücklichen Rundungsregel gerundet und hängen daher weder von der JSON-Bibliothek noch vom Datenbankprovider ab.
  • UTC-Zeitstempel. Das Mapping setzt die Art jedes Datums in beiden Versionen ausdrücklich; sonst würde das Suffix Z aus dem JSON verschwinden.

Was der Vertrag gefahrlos zu ändern erlaubt

Sobald der Vertrag grün ist, kann der interne Umbau ohne Sorge stattfinden, denn nichts davon darf eine Antwort verändern. Im Beispiel wurde Konfiguration aus statischen Einstellungen zu einer gebundenen Options-Klasse, der statische Service Locator wich der Konstruktorinjektion, eine statische Uhr wurde zu einem injizierten TimeProvider, und der in jeder Methode erzeugte Kontext von Entity Framework 6 wurde zu einem EF-Core-Kontext pro Anfrage mit explizitem Laden. Die alten Tests mussten wegen statischer Zustände nacheinander laufen, die migrierten laufen parallel.

Die Datenschicht verdient eigene Aufmerksamkeit. Entity Framework 6 läuft auf modernem .NET und muss daher nicht zusammen mit der Webschicht umziehen. Diese Entscheidung beschreiben wir in unserem Artikel und unseren Leistungen zur Migration von Entity Framework 6 zu EF Core.

So schreiben Sie den Vertrag für Ihre eigene API

  1. Echte Anfragen sammeln. Nutzen Sie Zugriffsprotokolle, die Testsuiten der Client-Anwendungen und die Dokumentation für Partner. Decken Sie jeden Endpunkt ab, den ein Client außerhalb Ihres Teams aufruft.
  2. Fehlerfälle aufnehmen. Unbekannte IDs, ungültige Inhalte, fehlende Anmeldedaten und falsche Content-Types sind die Stellen, an denen sich Frameworks am stärksten unterscheiden.
  3. Exakt vergleichen. Statuscode, Eigenschaftsnamen samt Schreibweise, Fehlerantworten und Header wie Location.
  4. Zuerst gegen den alten Dienst ausführen. Der Vertrag beschreibt, was der Dienst heute tut, nicht, was in der Dokumentation steht.
  5. Dieselbe Datei bei jedem Push gegen den neuen Dienst ausführen und jede Abweichung als Entscheidung behandeln: für bestehende Clients beibehalten oder bewusst ändern und die Clients informieren.

Den Migrationspfad wählen

Der Vertrag funktioniert mit jedem Pfad. Kleine und mittelgroße Dienste werden meist parallel portiert: ein neues ASP.NET-Core-Projekt neben dem bestehenden. Große Dienste ziehen schrittweise hinter einem Reverse Proxy um, der jede Anfrage an die alte oder die neue Implementierung leitet, Endpunktgruppe für Endpunktgruppe. Sehr kleine Dienste lassen sich mit Minimal APIs neu aufbauen, mit dem Vertrag als einzigem Fixpunkt.

Was das Beispiel ausklammert

Der alte Dienst im Beispiel läuft auf OWIN und nicht auf IIS mit System.Web. Das hält ihn klein und erlaubt es den Tests, ihn im Arbeitsspeicher zu hosten. Die Authentifizierung geht nicht über einen API-Schlüssel im Header hinaus. Die migrierte Anwendung wird nicht gegen die Datenbank getestet, die Entity Framework 6 angelegt hat. WCF-Dienste, Web Forms und Windows-Dienste brauchen andere Ansätze. Ein echtes Projekt muss diese Punkte in der eigenen Analyse abdecken.

Fazit

Eine Portierung nach ASP.NET Core, die sich kompilieren lässt, beweist sehr wenig. In unserem Beispiel bewies sie nichts: 0 von 17 Fällen bestanden, und die Ursache war eine Standardeinstellung, kein Fehler im Code. Das Verhalten der alten API als Vertrag festzuhalten, kostet am Projektanfang einige Tage und macht aus jeder versteckten Abweichung eine sichtbare, günstige Entscheidung.

Wenn Sie einen solchen Umzug planen, analysiert unser Team Ihren Dienst im Rahmen unserer Leistungen zur Migration von ASP.NET Web API zu ASP.NET Core. Und wenn Sie die Methode zuerst im Code sehen möchten: Das Beispiel auf GitHub läuft mit dem .NET 10 SDK.

Wir verwenden technisch notwendige Cookies, um die einwandfreie Funktion unserer Website sicherzustellen. Mit Ihrer Einwilligung verwenden wir außerdem optionale Cookies für Analysezwecke und weitere Funktionen. Sie können alle Cookies akzeptieren, optionale Cookies ablehnen oder Ihre Einstellungen individuell anpassen. Weitere Informationen finden Sie in unserer Cookie-Richtlinie.