Von .NET Framework 4.8 zu .NET 10: Migration einer Web-API am Beispiel

Die meisten Ratgeber zum Umstieg von .NET Framework auf modernes .NET sind Listen von API-Ersetzungen. Dieses Fallbeispiel zeigt den Teil, der in solchen Listen fehlt: den Nachweis, dass sich der migrierte Dienst für seine Clients noch genauso verhält. Es ist ein vollständiges, lauffähiges Beispiel mit der Anwendung vor der Migration, der Anwendung danach und einem Satz von Tests, den beide bestehen müssen.

Der Code liegt auf GitHub: chudovo/application-modernization, Case 01. Code und Kommentare sind auf Englisch. Diese Seite beschreibt, was gemacht wurde und was unterwegs schiefging.

Auf einen Blick

VorherNachher
Laufzeit.NET Framework 4.8.NET 10
WebASP.NET Web API 2 auf OWINASP.NET-Core-Controller
DatenzugriffEntity Framework 6, Lazy LoadingEF Core 10, explizites Include
JSONJson.NETSystem.Text.Json
KonfigurationConfigurationManager, statische Klasseappsettings.json, Options
Abhängigkeitenstatischer Service Locatorintegrierte Dependency Injection
Testsseriell, SQL Server LocalDBparallel, SQLite im Arbeitsspeicher

Die Ausgangslage

Die Altanwendung ist eine Auftrags-API mit vier Endpunkten: Auftrag lesen, Aufträge suchen, Auftrag mit Rabatt- und Umsatzsteuerberechnung anlegen, Auftrag stornieren. Sie ist klein, hat aber die Gewohnheiten, die echte .NET-Framework-Dienste schwer migrierbar machen:

  • Controller holen ihre Abhängigkeiten in einem parameterlosen Konstruktor aus einem statischen Service Locator.
  • Einstellungen werden über eine statische Klasse auf Basis von ConfigurationManager gelesen.
  • Die aktuelle Zeit kommt aus einem statischen Delegaten, den Tests überschreiben.
  • Der Entity-Framework-6-Kontext wird in jeder Service-Methode erzeugt und verlässt sich auf Lazy Loading.
  • Alles läuft synchron.
public class OrdersController : ApiController
{
    // Web API 2 instantiates controllers through the parameterless constructor.
    public OrdersController() : this(ServiceLocator.Resolve<OrderService>()) { }

    [HttpGet, Route("{id:int}", Name = "GetOrder")]
    public IHttpActionResult Get(int id)
    {
        var order = _orders.Get(id);
        if (order == null) return NotFound();
        return Ok(OrderDto.From(order));
    }
}

Schritt 1: das Verhalten festhalten, bevor Code angefasst wird

Das erste Ergebnis war kein Code, sondern eine Datei mit 17 HTTP-Fällen, die beschreiben, was die Alt-API tut: Statuscodes, exakte Eigenschaftsnamen, Fehlerinhalte und der Location-Header. Einer davon:

{ "name": "unknown order is a 404 with an empty body",
  "request": { "method": "GET", "path": "/api/orders/999", "apiKey": true },
  "expect": { "status": 404, "emptyBody": true } }

Eigenschaftsnamen werden unter Beachtung der Groß- und Kleinschreibung verglichen, denn Id und id sind für einen Client, der in ein typisiertes Modell deserialisiert, zwei verschiedene Verträge. Die Tests der Altanwendung führen diese Datei gegen Web API 2 im Arbeitsspeicher aus, die Tests der migrierten Anwendung dieselbe Datei gegen ASP.NET Core. Die Datei weiß nicht, welches Framework antwortet.

Schritt 2: die direkte Portierung bestand 0 von 17 Fällen

Die Controller wurden auf dem naheliegenden Weg portiert: Aus ApiController wurde ControllerBase, aus IHttpActionResult wurde IActionResult, aus dem Message Handler eine Middleware. Der Code kompilierte und las sich korrekt. Gegen den Vertrag scheiterte jeder Fall.

SchrittBestandenWas falsch war
Direkte Portierung, Framework-Standards0 / 17alle Antworten verwendeten camelCase-Eigenschaftsnamen
Eigenschaftsnamen wie deklariert14 / 17drei Unterschiede blieben
Kompatibilitätseinstellungen17 / 17

Die erste Ursache ist bekannt: Web API 2 schreibt Eigenschaftsnamen so, wie sie in C# deklariert sind, ASP.NET Core wandelt sie in camelCase um. Eine Zeile behebt das, danach bestehen 14 Fälle. Die übrigen drei sind die, die in Produktion landen, wenn niemand darauf testet:

  • 404 mit Inhalt. NotFound() liefert in einem Controller mit [ApiController] einen ProblemDetails-JSON-Inhalt. Die Alt-API antwortete mit 404 ohne Inhalt.
  • Ungültiges JSON erreichte die Action nie. [ApiController] beantwortet einen fehlerhaften Body selbst, in einem eigenen Fehlerformat. Die Alt-API führte die Action aus und lieferte { "Message": "..." }.
  • Der API-Key-Fehler kam in camelCase. Antworten aus einer Middleware verwenden andere JSON-Optionen als MVC, die Korrektur für die Controller galt dort also nicht.

Alle drei sind an einer Stelle geregelt, jeweils mit einem Kommentar, welches Altverhalten erhalten bleibt:

builder.Services.AddControllers()
    // Web API 2 wrote property names exactly as declared in C#. ASP.NET Core camel-cases them by default.
    .AddJsonOptions(o => o.JsonSerializerOptions.PropertyNamingPolicy = null)
    .ConfigureApiBehaviorOptions(o =>
    {
        // [ApiController] answers invalid input by itself with a ProblemDetails body. The legacy API let the
        // action run and returned { "Message": ... }, and clients parse that shape.
        o.SuppressModelStateInvalidFilter = true;
        // Likewise, NotFound() would get a ProblemDetails body. The legacy API returned 404 with no body.
        o.SuppressMapClientErrors = true;
    });

// Responses written outside MVC (the API key middleware) use a separate set of JSON options.
builder.Services.ConfigureHttpJsonOptions(o => o.SerializerOptions.PropertyNamingPolicy = null);

Was nicht kaputtging, obwohl es das oft tut

  • Zahlen als Zeichenketten. Alte Clients senden "Quantity": "3". Json.NET akzeptiert das. System.Text.Json lehnt es standardmäßig ab, ASP.NET Core konfiguriert es jedoch mit Web-Standardwerten, die es akzeptieren. Der Vertrag enthält dafür einen Fall, er bestand ohne Änderung.
  • Eigenschaftsnamen in Anfragen ohne Beachtung der Groß- und Kleinschreibung. Gleicher Grund.
  • Geldbeträge. Summen werden im Domänencode mit einem expliziten Rundungsmodus gerundet und hängen daher weder von der JSON-Bibliothek noch vom Datenbankanbieter ab.
  • UTC-Zeitstempel. Beide Datenbanken liefern Datumswerte ohne Zeitzonenangabe. Das Mapping setzt sie in beiden Versionen explizit, sonst verschwindet das Z aus dem JSON.

Schritt 3: die Änderungen, die der Vertrag nicht sieht

Mit grünem Vertrag konnte das Innenleben gefahrlos geändert werden. Keine dieser Änderungen verändert eine einzige Antwort, und genau darum geht es.

Der Datenzugriff ist das deutlichste Beispiel. Die EF6-Version braucht eine Hilfsmethode, die Navigationseigenschaften anfasst, damit sie geladen sind, bevor der Kontext verworfen wird. Fehlt der Aufruf in einer Methode, scheitert die API bei der Serialisierung:

public Order Get(int id)
{
    using (var db = _contextFactory())
    {
        var order = db.Orders.Find(id);
        if (order == null) return null;
        Touch(order);   // forces lazy-loaded Customer and Lines to load before the context is disposed
        return order;
    }
}

Die EF-Core-Version hat einen Kontext pro Anfrage und sagt ausdrücklich, was sie lädt:

private IQueryable<Order> OrdersWithDetails => db.Orders.Include(o => o.Customer).Include(o => o.Lines);

public Task<Order?> GetAsync(int id, CancellationToken ct) =>
    OrdersWithDetails.SingleOrDefaultAsync(o => o.Id == id, ct);
  • Aus der statischen Einstellungsklasse wurde ein Options-Objekt, das dem Preisdienst übergeben wird.
  • Service Locator und parameterlose Konstruktoren sind entfallen. Abhängigkeiten sind Konstruktorparameter.
  • Aus der statischen Uhr wurde ein injizierter TimeProvider.
  • EF6 bildet decimal standardmäßig auf decimal(18,2) ab. EF Core hat keinen Standard, daher ist die Genauigkeit des bestehenden Schemas ausdrücklich angegeben.
  • Die Tests der Altanwendung können nicht parallel laufen, weil der Zustand statisch ist. Die Tests der migrierten Anwendung laufen parallel, jeder mit eigener Datenbank im Arbeitsspeicher.

Was dieses Beispiel auslässt

  • Hosting auf IIS mit System.Web, Global.asax und HttpContext.Current. Die Altanwendung läuft hier auf OWIN, das hält sie klein und im Arbeitsspeicher testbar.
  • Authentifizierung über einen API-Key-Header hinaus.
  • Den Betrieb der migrierten Anwendung auf der Datenbank, die EF6 angelegt hat. Das Schema ist kompatibel angelegt, in diesem Fallbeispiel aber nicht getestet.
  • WCF, Web Forms und Windows-Dienste. Jedes braucht einen eigenen Ansatz und bekommt ein eigenes Fallbeispiel.

Selbst ausführen

Die migrierte Anwendung benötigt nur das .NET 10 SDK und läuft auf jedem Betriebssystem:

git clone https://github.com/chudovo/application-modernization
cd application-modernization/cases/01-net-framework-to-net10/after
dotnet test

Die Altanwendung benötigt Windows mit SQL Server LocalDB. Beide Versionen werden bei jedem Push in GitHub Actions gebaut und getestet. Details stehen in der README des Fallbeispiels.

Dieses Fallbeispiel ersetzt die Laufzeit und mit ihr die Datenzugriffsbibliothek. Ist die Laufzeit bereits modern und nur Entity Framework 6 übrig, zeigt das folgende Fallbeispiel die Datenbankseite im Detail: Von Entity Framework 6 zu EF Core auf einer bestehenden Datenbank: ein Fallbeispiel.

Wann dieser Weg passt

Dieses Fallbeispiel ist ein Wechsel auf eine neue Laufzeit mit gezieltem Refactoring, keine Neuentwicklung. Der Weg passt zu einem Dienst, dessen Verhalten noch stimmt und dessen Plattform das Problem ist. Wie Sie zwischen diesem Weg, einem tieferen Reengineering und einer Neuentwicklung entscheiden, beschreibt der Leitfaden Anwendungsmodernisierung: den richtigen Weg für eine Anwendung wählen.

Ein verwandtes Fallbeispiel überführt einen WCF-Dienst in eine REST-API und hält dabei die SOAP-Clients am Laufen: Von WCF zur ASP.NET-Core-Web-API.

Wenn Sie für eine solche Migration ein Team suchen, finden Sie hier unseren Vergleich der Top-Unternehmen für .NET-Modernisierung.

Eugene begann seine Karriere bei Chudovo im Jahr 2015. Der Experte ist für Beratungsleistungen verantwortlich, die unter anderem eine enge Kommunikation mit den Kunden, die Analyse ihrer Bedürfnisse, die Entwicklung maßgeschneiderter Softwarestrategien usw. umfassen. Während seiner Tätigkeit bei Chudovo nahm ein IT-Berater an über 17 Projekten teil, die ein breites Spektrum an Kundendienstleistungen abdeckten und Kundenprobleme aus geschäftlicher Sicht lösten. Dank Eugenes Beteiligung konnten die Kunden eine effiziente Strategie für das Geschäftswachstum sowie eine langfristige Technologie-Roadmap entwickeln. Eugene nimmt in der Rolle des IT-Beraters aktiv an Softwareentwicklungsprojekten teil und erstellt Vorschläge für die Kunden.