WCF does not exist in modern .NET, so a WCF service cannot simply be recompiled. The usual advice is to rewrite it as a REST API. That advice skips the hard part: the service has clients, they speak SOAP, and they cannot all be changed on the same day. This case shows a migration that does not require them to.
The code is on GitHub: chudovo/application-modernization, case 02. It contains the WCF service, the migrated service, and one set of scenarios that is run against both.
At a glance
| Before | After | |
|---|---|---|
| Runtime | .NET Framework 4.8 | .NET 10 |
| Protocol | SOAP over HTTP | REST with JSON, plus the same SOAP contract through CoreWCF |
| Where the rules live | inside the WCF service class | a core library that knows nothing about SOAP or HTTP |
| Errors | typed SOAP faults | domain exceptions, mapped per protocol |
| Caller identity | ambient OperationContext | an explicit parameter |
| State and time | static classes | injected services |
The starting point
The legacy service tracks shipments: look one up, search, create, change the status, quote a rate. It is written the way WCF services usually were. The service class is the application:
[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";
}
}
Three things in this class block a migration. Business rules throw a transport-specific exception type. State is static. And the caller is read from an ambient context that only exists inside a WCF call.
Step 1: scenarios that do not mention the protocol
SOAP and REST cannot share an HTTP-level test, so the behaviour is written down as operations and outcomes:
{ "name": "a delivered shipment cannot go back into transit",
"op": "UpdateStatus", "args": { "trackingNumber": "SHP-000003", "newStatus": "InTransit" },
"expect": { "error": { "kind": "InvalidTransition" } } }
Each test suite has a small client that performs the operation over its own protocol and turns the answer into the same neutral shape. There are 16 scenarios. They were written against the legacy service first, and passed 16 of 16 on .NET Framework before anything moved.
Step 2: pull the rules out of the service class
The rules move into a library with no reference to WCF, ASP.NET Core or JSON. Errors are plain exceptions. The caller is a 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) { ... }
}
This step is the actual modernization. Everything after it is plumbing.
Step 3: host the unchanged contract on .NET 10
The SOAP contract is not rewritten. The new solution compiles the same IShipmentService.cs file that the legacy service uses, and CoreWCF hosts it inside the ASP.NET Core application. The service class is now an adapter: map the request, call the core, map the result or the fault.
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));
}
...
}
}
To check that this really keeps old clients working, the test suite calls the new endpoint with a WCF client, a ChannelFactory over basicHttpBinding, as existing .NET consumers do. All 16 scenarios pass, including the typed faults.
Step 4: add the REST API on the same core
The REST endpoints sit next to the SOAP endpoint in one application and share one store. Each operation is mapped deliberately:
| WCF operation | REST |
|---|---|
| GetShipment(trackingNumber) | GET /api/shipments/{trackingNumber} |
| FindShipments(query) | GET /api/shipments?status=&countryCode= |
| CreateShipment(request) | POST /api/shipments, answers 201 with a 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));
});
The rate quote is a calculation with no resource behind it. It stays an RPC-style POST instead of being forced into a resource shape. Typed faults become status codes with a machine-readable code:
HTTP/1.1 409 Conflict
{ "title": "Cannot change status from Delivered to InTransit.", "status": 409,
"code": "invalid_transition", "from": "Delivered", "to": "InTransit" }
Three runs, one set of scenarios
| Run | Client | Result |
|---|---|---|
| Legacy WCF service on .NET Framework 4.8 | WCF client | 16 / 16 |
| New SOAP endpoint on .NET 10 | WCF client | 16 / 16 |
| New REST API on .NET 10 | HTTP client | 16 / 16, plus one REST-only test |
The second row is the one that matters for planning. A client built for the old service calls the new one unchanged, so clients can be moved to REST one at a time, and the SOAP endpoint is removed when the last one is gone.
What went wrong on the way
- CoreWCF pulled ASP.NET Core 2.x packages into the test project. In a web project the shared framework replaces them. The test project is a plain library, so the old packages were restored, and the build failed on a known vulnerability in one of them. A framework reference in the test project fixes it.
- A request that cannot be bound got a bare 400. Sending an unknown status name to the REST API returned 400 with an empty body, while every other error returned a ProblemDetails document. One option routes that failure through the same handler as the domain errors.
- The legacy tests deadlocked. A WCF host opened on a thread with a synchronization context dispatches every call back to that context. The test runner has one, and the test thread was blocked in the client call. Opening the host on a thread-pool thread fixed it. The same behaviour bites WCF services hosted inside desktop applications.
What worked on the first run, although it often does not: the contract file compiled for .NET 10 without changes, typed faults reached the WCF client as the same types, an optional element was omitted and read back as null, and the HTTP header with the caller identity was available through CoreWCF.
What this example leaves out
- WS-Security, message-level encryption and transport security.
netTcpBinding, duplex contracts, sessions and transactions. CoreWCF covers some of these, not all.- WSDL publishing for the new SOAP endpoint, and generated client proxies.
- A database. The store is in memory in both versions, to keep the example about the service layer.
Run it yourself
The migrated service needs only the .NET 10 SDK and runs on any operating system:
git clone https://github.com/chudovo/application-modernization
cd application-modernization/cases/02-wcf-to-web-api/after
dotnet test
The legacy service needs Windows. Both versions are built and tested on every push in GitHub Actions. Details are in the README of the case.
When this path fits
Keeping the SOAP contract alive is worth it when the service has clients you do not control or cannot release together with the service. If the only client is your own front end, moving straight to REST is simpler. The broader decision between refactoring, reengineering and rebuilding is covered in Application Modernization Strategy: Choosing the Path for One Application. A related case moves a Web API from .NET Framework to .NET 10 without changing its protocol: .NET Framework 4.8 Web API to .NET 10.
The mobile app that uses this service is migrated from Xamarin.Forms to .NET MAUI in a separate case: Xamarin.Forms to .NET MAUI.
If you need a team for a migration like this, see our comparison of top .NET modernization companies.