Von WCF zur ASP.NET-Core-Web-API: Migration am Beispiel

WCF gibt es im modernen .NET nicht, ein WCF-Dienst lässt sich also nicht einfach neu kompilieren. Der übliche Rat lautet, ihn als REST-API neu zu schreiben. Dieser Rat überspringt den schwierigen Teil: Der Dienst hat Clients, sie sprechen SOAP, und sie lassen sich nicht alle am selben Tag umstellen. Dieses Fallbeispiel zeigt eine Migration, die das auch nicht verlangt.

Der Code liegt auf GitHub: chudovo/application-modernization, Case 02. Code und Kommentare sind auf Englisch. Enthalten sind der WCF-Dienst, der migrierte Dienst und ein Satz von Szenarien, der gegen beide läuft.

Auf einen Blick

VorherNachher
Laufzeit.NET Framework 4.8.NET 10
ProtokollSOAP über HTTPREST mit JSON, dazu derselbe SOAP-Vertrag über CoreWCF
Ort der Regelnin der WCF-Dienstklasseeine Kernbibliothek, die weder SOAP noch HTTP kennt
Fehlertypisierte SOAP-FaultsDomänenausnahmen, je Protokoll abgebildet
Identität des Aufrufersambienter OperationContextein expliziter Parameter
Zustand und Zeitstatische Klasseninjizierte Dienste

Die Ausgangslage

Der Altdienst verwaltet Sendungen: eine Sendung abrufen, suchen, anlegen, den Status ändern, einen Tarif berechnen. Er ist so geschrieben, wie WCF-Dienste üblicherweise geschrieben wurden. Die Dienstklasse ist die Anwendung:

[ServiceBehavior(InstanceContextMode = InstanceContextMode.Single, ConcurrencyMode = ConcurrencyMode.Single)]
public class ShipmentService : IShipmentService
{
    public ShipmentData GetShipment(string trackingNumber)
    {
        var shipment = ShipmentStore.Find(trackingNumber);          // static state
        if (shipment == null)
            throw new FaultException<NotFoundFault>(                 // transport error type in business code
                new NotFoundFault { TrackingNumber = trackingNumber },
                new FaultReason("Shipment " + trackingNumber + " was not found."));
        return shipment;
    }

    // The caller is identified by an HTTP header, read from the ambient WCF operation context.
    private static string CallerId()
    {
        object property;
        if (OperationContext.Current != null &&
            OperationContext.Current.IncomingMessageProperties.TryGetValue(HttpRequestMessageProperty.Name, out property))
        { ... }
        return "unknown";
    }
}

Drei Dinge in dieser Klasse stehen einer Migration im Weg. Geschäftsregeln werfen einen transportspezifischen Ausnahmetyp. Der Zustand ist statisch. Und der Aufrufer wird aus einem ambienten Kontext gelesen, den es nur innerhalb eines WCF-Aufrufs gibt.

Schritt 1: Szenarien, die das Protokoll nicht erwähnen

SOAP und REST können keinen Test auf HTTP-Ebene teilen, also wird das Verhalten als Operationen und Ergebnisse festgehalten:

{ "name": "a delivered shipment cannot go back into transit",
  "op": "UpdateStatus", "args": { "trackingNumber": "SHP-000003", "newStatus": "InTransit" },
  "expect": { "error": { "kind": "InvalidTransition" } } }

Jede Testsuite hat einen kleinen Client, der die Operation über sein Protokoll ausführt und die Antwort in dieselbe neutrale Form bringt. Es gibt 16 Szenarien. Sie wurden zuerst gegen den Altdienst geschrieben und bestanden auf .NET Framework 16 von 16, bevor irgendetwas verschoben wurde.

Schritt 2: die Regeln aus der Dienstklasse herauslösen

Die Regeln wandern in eine Bibliothek ohne Bezug zu WCF, ASP.NET Core oder JSON. Fehler sind gewöhnliche Ausnahmen, der Aufrufer ist ein Parameter.

public class ShipmentManager(ShipmentStore store, TimeProvider clock)
{
    public Shipment Get(string? trackingNumber) =>
        store.Find(trackingNumber) ?? throw new ShipmentNotFoundException(trackingNumber);

    public Shipment Create(NewShipment? request, string? callerId) { ... }
}

Dieser Schritt ist die eigentliche Modernisierung. Alles danach ist Verdrahtung.

Schritt 3: den unveränderten Vertrag auf .NET 10 hosten

Der SOAP-Vertrag wird nicht neu geschrieben. Die neue Lösung kompiliert dieselbe Datei IShipmentService.cs, die der Altdienst verwendet, und CoreWCF hostet sie in der ASP.NET-Core-Anwendung. Die Dienstklasse ist jetzt ein Adapter: Anfrage abbilden, Kern aufrufen, Ergebnis oder Fault abbilden.

public class SoapShipmentService(ShipmentManager shipments, RateCalculator rates) : IShipmentService
{
    public ShipmentData GetShipment(string trackingNumber) => Call(() => ToData(shipments.Get(trackingNumber)));

    // Domain exceptions become the same typed faults the legacy service declared in its contract.
    private static T Call<T>(Func<T> operation)
    {
        try { return operation(); }
        catch (ShipmentNotFoundException e)
        {
            throw new FaultException<NotFoundFault>(new NotFoundFault { TrackingNumber = e.TrackingNumber }, new FaultReason(e.Message));
        }
        ...
    }
}

Um zu prüfen, dass alte Clients damit wirklich weiterlaufen, ruft die Testsuite den neuen Endpunkt mit einem WCF-Client auf, einer ChannelFactory über basicHttpBinding, so wie es bestehende .NET-Konsumenten tun. Alle 16 Szenarien bestehen, einschließlich der typisierten Faults.

Schritt 4: die REST-API auf demselben Kern ergänzen

Die REST-Endpunkte liegen neben dem SOAP-Endpunkt in einer Anwendung und teilen sich einen Speicher. Jede Operation wird bewusst abgebildet:

WCF-OperationREST
GetShipment(trackingNumber)GET /api/shipments/{trackingNumber}
FindShipments(query)GET /api/shipments?status=&countryCode=
CreateShipment(request)POST /api/shipments, antwortet mit 201 und Location-Header
UpdateStatus(trackingNumber, newStatus)PUT /api/shipments/{trackingNumber}/status
QuoteRate(weightKg, countryCode, service)POST /api/rates/quote
// GetShipment(trackingNumber) -> a resource addressed by its identifier.
api.MapGet("/shipments/{trackingNumber}", (string trackingNumber, ShipmentManager shipments) =>
    ShipmentResponse.From(shipments.Get(trackingNumber)));

// The caller identity was read from the ambient OperationContext. Here it is an explicit parameter.
api.MapPost("/shipments", (CreateShipmentBody body, [FromHeader(Name = "X-Client-Id")] string? clientId, ShipmentManager shipments) =>
{
    var created = shipments.Create(new NewShipment(...), clientId);
    return Results.Created($"/api/shipments/{created.TrackingNumber}", ShipmentResponse.From(created));
});

Die Tarifberechnung ist eine Berechnung ohne Ressource dahinter. Sie bleibt ein POST im RPC-Stil und wird nicht in eine Ressourcenform gezwungen. Aus typisierten Faults werden Statuscodes mit einem maschinenlesbaren Code:

HTTP/1.1 409 Conflict

{ "title": "Cannot change status from Delivered to InTransit.", "status": 409,
  "code": "invalid_transition", "from": "Delivered", "to": "InTransit" }

Drei Durchläufe, ein Satz Szenarien

DurchlaufClientErgebnis
WCF-Altdienst auf .NET Framework 4.8WCF-Client16 / 16
Neuer SOAP-Endpunkt auf .NET 10WCF-Client16 / 16
Neue REST-API auf .NET 10HTTP-Client16 / 16, dazu ein Test nur für REST

Die zweite Zeile ist für die Planung entscheidend. Ein Client, der für den alten Dienst gebaut wurde, ruft den neuen unverändert auf. Clients lassen sich so einzeln auf REST umstellen, und der SOAP-Endpunkt entfällt, wenn der letzte umgezogen ist.

Was unterwegs schiefging

  • CoreWCF zog ASP.NET-Core-2.x-Pakete in das Testprojekt. In einem Webprojekt ersetzt das Shared Framework diese Pakete. Das Testprojekt ist eine gewöhnliche Bibliothek, also wurden die alten Pakete wiederhergestellt, und der Build scheiterte an einer bekannten Schwachstelle in einem davon. Ein Framework-Verweis im Testprojekt behebt das.
  • Eine nicht bindbare Anfrage bekam ein nacktes 400. Ein unbekannter Statusname an die REST-API lieferte 400 mit leerem Body, während jeder andere Fehler ein ProblemDetails-Dokument lieferte. Eine Option leitet auch diesen Fehler durch denselben Handler wie die Domänenfehler.
  • Die Tests des Altdienstes blockierten sich gegenseitig. Ein WCF-Host, der auf einem Thread mit Synchronisierungskontext geöffnet wird, leitet jeden Aufruf an diesen Kontext zurück. Der Test-Runner hat einen, und der Test-Thread wartete im Client-Aufruf. Das Öffnen des Hosts auf einem Thread-Pool-Thread löste das. Dasselbe Verhalten trifft WCF-Dienste, die in Desktop-Anwendungen gehostet werden.

Was beim ersten Durchlauf funktionierte, obwohl es das oft nicht tut: Die Vertragsdatei kompilierte ohne Änderung für .NET 10, typisierte Faults kamen beim WCF-Client als dieselben Typen an, ein optionales Element wurde weggelassen und als null gelesen, und der HTTP-Header mit der Identität des Aufrufers war über CoreWCF verfügbar.

Was dieses Beispiel auslässt

  • WS-Security, Verschlüsselung auf Nachrichtenebene und Transportsicherheit.
  • netTcpBinding, Duplex-Verträge, Sessions und Transaktionen. CoreWCF deckt einiges davon ab, nicht alles.
  • Die Veröffentlichung von WSDL für den neuen SOAP-Endpunkt und generierte Client-Proxys.
  • Eine Datenbank. Der Speicher liegt in beiden Versionen im Arbeitsspeicher, damit es im Beispiel um die Dienstschicht geht.

Selbst ausführen

Der migrierte Dienst 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/02-wcf-to-web-api/after
dotnet test

Der Altdienst benötigt Windows. Beide Versionen werden bei jedem Push in GitHub Actions gebaut und getestet. Details stehen in der README des Fallbeispiels.

Wann dieser Weg passt

Den SOAP-Vertrag am Leben zu halten lohnt sich, wenn der Dienst Clients hat, die Sie nicht kontrollieren oder nicht gemeinsam mit dem Dienst ausliefern können. Ist der einzige Client Ihr eigenes Frontend, ist der direkte Wechsel zu REST einfacher. Die grundsätzliche Entscheidung zwischen Refactoring, Reengineering und Neuentwicklung behandelt der Leitfaden Anwendungsmodernisierung: den richtigen Weg für eine Anwendung wählen. Ein verwandtes Fallbeispiel überführt eine Web-API von .NET Framework nach .NET 10, ohne das Protokoll zu ändern: Von .NET Framework 4.8 zu .NET 10.

Die mobile App, die diesen Dienst nutzt, wird in einem eigenen Fallbeispiel von Xamarin.Forms auf .NET MAUI migriert: Von Xamarin.Forms zu .NET MAUI.

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.