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
| Vorher | Nachher | |
|---|---|---|
| Laufzeit | .NET Framework 4.8 | .NET 10 |
| Web | ASP.NET Web API 2 auf OWIN | ASP.NET-Core-Controller |
| Datenzugriff | Entity Framework 6, Lazy Loading | EF Core 10, explizites Include |
| JSON | Json.NET | System.Text.Json |
| Konfiguration | ConfigurationManager, statische Klasse | appsettings.json, Options |
| Abhängigkeiten | statischer Service Locator | integrierte Dependency Injection |
| Tests | seriell, SQL Server LocalDB | parallel, 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
ConfigurationManagergelesen. - 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.
| Schritt | Bestanden | Was falsch war |
|---|---|---|
| Direkte Portierung, Framework-Standards | 0 / 17 | alle Antworten verwendeten camelCase-Eigenschaftsnamen |
| Eigenschaftsnamen wie deklariert | 14 / 17 | drei Unterschiede blieben |
| Kompatibilitätseinstellungen | 17 / 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
Zaus 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
decimalstandardmäßig aufdecimal(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.asaxundHttpContext.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.