Most advice on moving from .NET Framework to modern .NET is a list of API replacements. This case shows the part that list leaves out: how to prove that the migrated service still behaves the same for its clients. It is a complete, runnable example with the application before the migration, the application after it, and one set of tests that both must pass.
The code is on GitHub: chudovo/application-modernization, case 01. This page walks through what was done and what went wrong on the way.
At a glance
| Before | After | |
|---|---|---|
| Runtime | .NET Framework 4.8 | .NET 10 |
| Web | ASP.NET Web API 2 on OWIN | ASP.NET Core controllers |
| Data access | Entity Framework 6, lazy loading | EF Core 10, explicit Include |
| JSON | Json.NET | System.Text.Json |
| Configuration | ConfigurationManager, static class | appsettings.json, options |
| Dependencies | static service locator | built-in dependency injection |
| Tests | serial, SQL Server LocalDB | parallel, in-memory SQLite |
The starting point
The legacy application is an order API with four endpoints: read an order, search orders, create an order with discount and VAT calculation, and cancel an order. It is small, but it has the habits that make real .NET Framework services hard to move:
- Controllers get their dependencies from a static service locator in a parameterless constructor.
- Settings are read through a static class on top of
ConfigurationManager. - The current time comes from a static delegate that tests overwrite.
- The Entity Framework 6 context is created inside each service method and relies on lazy loading.
- Everything is synchronous.
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));
}
}
Step 1: write the behaviour down before touching the code
The first deliverable was not code. It was a file of 17 HTTP cases that describe what the legacy API does: status codes, exact property names, error bodies and the Location header. One of them:
{ "name": "unknown order is a 404 with an empty body",
"request": { "method": "GET", "path": "/api/orders/999", "apiKey": true },
"expect": { "status": 404, "emptyBody": true } }
Property names are compared case-sensitively, because Id and id are different contracts for a client that deserializes into a typed model. The legacy test suite runs this file against Web API 2 hosted in memory. The migrated test suite runs the same file against ASP.NET Core. Nothing in the file knows which framework answers.
Step 2: the straight port passed 0 of 17
The controllers were ported the obvious way: ApiController became ControllerBase, IHttpActionResult became IActionResult, the message handler became middleware. The code compiled and read correctly. Against the contract it failed every case.
| Step | Passing | What was wrong |
|---|---|---|
| Straight port, framework defaults | 0 / 17 | every response body used camelCase property names |
| Keep property names as declared | 14 / 17 | three differences left |
| Compatibility settings | 17 / 17 |
The first cause is well known: Web API 2 writes property names as declared in C#, ASP.NET Core camel-cases them. One line fixes it, and 14 cases pass. The remaining three are the ones that reach production when nobody tests for them:
- 404 with a body.
NotFound()in a controller marked[ApiController]returns a ProblemDetails JSON body. The legacy API returned 404 with an empty body. - Invalid JSON never reached the action.
[ApiController]answers a malformed body itself, with its own error format. The legacy API ran the action and returned{ "Message": "..." }. - The API key error was camel-cased. Responses written from middleware use a different set of JSON options than MVC, so the naming fix for controllers did not apply to them.
All three are settled in one place, each with a comment that says which legacy behaviour it preserves:
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);
What did not break, although it often does
- Numbers sent as strings. Old clients send
"Quantity": "3". Json.NET accepts that. System.Text.Json rejects it by default, but ASP.NET Core configures it with web defaults, which accept it. The contract has a case for it, and it passed without changes. - Case-insensitive request property names. Same reason.
- Money. Totals are rounded in the domain code with an explicit rounding mode, so they do not depend on the JSON library or the database provider.
- UTC timestamps. Both databases return dates without a time zone marker. The mapping sets it explicitly in both versions, otherwise the
Zsuffix disappears from the JSON.
Step 3: the changes the contract cannot see
With the contract green, the internals could change safely. None of these alter a single response, which is the point.
Data access is the clearest example. The EF6 version needs a helper that touches navigation properties so they load before the context is disposed. Forget the call in one method and the API fails during serialization:
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;
}
}
The EF Core version has one context per request and states what it loads:
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);
- The static settings class became an options object that is passed into the pricing service.
- The service locator and the parameterless constructors are gone. Dependencies are constructor parameters.
- The static clock became an injected
TimeProvider. - EF6 maps
decimaltodecimal(18,2)by default. EF Core has no default, so the precision of the existing schema is stated explicitly. - The legacy tests cannot run in parallel, because the application state is static. The migrated tests run in parallel, each with its own in-memory database.
What this example leaves out
- Hosting on IIS with
System.Web,Global.asaxandHttpContext.Current. The legacy application here is hosted on OWIN, which keeps it small and testable in memory. - Authentication beyond an API key header.
- Running the migrated application against the database that EF6 created. The schema is intended to be compatible, but that is not tested in this case.
- WCF, Web Forms and Windows services. Each needs a different approach and gets its own case.
Run it yourself
The migrated application needs only the .NET 10 SDK and runs on any operating system:
git clone https://github.com/chudovo/application-modernization
cd application-modernization/cases/01-net-framework-to-net10/after
dotnet test
The legacy application needs Windows with SQL Server LocalDB. Both versions are built and tested on every push in GitHub Actions. Details are in the README of the case.
This case replaces the runtime and, with it, the data access library. When the runtime is already modern and only Entity Framework 6 is left, the database side is shown in detail in Entity Framework 6 to EF Core on an Existing Database: A Worked Example.
When this path fits
This case is a move to a new runtime with targeted refactoring, not a rewrite. It fits a service whose behaviour is still right and whose platform is the problem. How to decide between this path, a deeper reengineering and a rebuild is covered in the guide Application Modernization Strategy: Choosing the Path for One Application.
A related case moves a WCF service to a REST API while keeping its SOAP clients working: WCF Service to ASP.NET Core Web API.
If you need a team for a migration like this, see our comparison of top .NET modernization companies.