DEV Community

Pedro Ávila
Pedro Ávila

Posted on

From .NET Framework 4.8 to .NET 10: What the Tool Did, What I Did, and What My Architecture Saved Me

I recently migrated a reference project of mine — a Customer API built with hexagonal
architecture and CQRS — from .NET Framework 4.8 to .NET 10. I used the
.NET Upgrade Assistant
for part of the work, did the rest by hand, and ended up with a result I can prove with git:
the domain and application layers did not change a single byte.

This is an honest account of that migration: what the tool actually did, what it could not do,
and why decisions I made before starting mattered more than the tool itself.

TL;DR

  • Upgrade Assistant converted the class libraries: SDK-style projects, PackageReference, new TFM.
  • It cannot rewrite System.Web. I rebuilt the host as a new ASP.NET Core project.
  • Entities, ports, DTOs and use-case handlers: byte-for-byte identical (same git blob hashes).
  • I deleted ~150 lines of DI plumbing, a custom ILogger, a custom ProblemDetails, and 8 binding redirects.
  • My own netstandard2.0 NuGet packages came along for free.

The starting point

The solution has seven projects, organised by layers:

Example.Api                  → ASP.NET Web API 2 host (net48)
Example.Dtos                 → commands, queries, results
Example.UseCase              → CQRS handlers + FluentValidation validators
Example.Entities             → domain entities
Example.Ports                → repository interfaces
Example.Adapters             → Dapper implementation
Infraestructure/
  Example.BuildingBlocks     → CQRS contracts, pipeline behaviours, exceptions
Enter fullscreen mode Exit fullscreen mode

The mediator is PAN.Mediator, a lightweight
library I wrote myself, and data access uses Dapper plus
PAN.DapperLambdaSQL for lambda-based
queries and partial updates.

The legacy host had the full System.Web ceremony: Global.asax, an App_Start folder with
five configuration classes, Web.config with transforms, and packages.config.

Why .NET 10? It is an LTS release (supported until November 2028), and everything I had been
simulating on net48 — dependency injection, logging, ProblemDetails — is built in.

The preparation nobody talks about

Here is the part most migration posts skip: the legacy code already had a modern shape.
Before touching the TFM, the net48 project was already using:

  • Microsoft.Extensions.DependencyInjection (yes, on .NET Framework),
  • ILogger<T> abstractions, backed by a tiny TraceLogger adapter over System.Diagnostics.Trace,
  • a mediator library targeting netstandard2.0.

So the application core did not depend on System.Web at all. The migration was about
replacing the host, not the application.

Lesson: modernise your abstractions before you migrate. Every System.Web dependency
you remove beforehand is one less thing to rewrite later.

What Upgrade Assistant actually did

For the six class libraries, the tool did the mechanical work:

  • Converted old-style csproj files to SDK-style.
  • Replaced packages.config with PackageReference.
  • Changed the target framework to net10.0.
  • Moved AssemblyInfo.cs attributes into MSBuild properties (all seven AssemblyInfo.cs files are gone).

You can see the tool's fingerprint in the converted project file:

<!-- Before: 14 KB of MSBuild ceremony, HintPaths to ..\packages\..., packages.config -->
<TargetFrameworkVersion>v4.8</TargetFrameworkVersion>
<Reference Include="FluentValidation">
  <HintPath>..\packages\FluentValidation.11.12.0\lib\netstandard2.0\FluentValidation.dll</HintPath>
</Reference>
Enter fullscreen mode Exit fullscreen mode
<!-- After: Example.BuildingBlocks.csproj, the whole file -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <AssemblyTitle>Example.BuildingBlocks</AssemblyTitle>
    <Product>Example.BuildingBlocks</Product>
    <AssemblyVersion>1.0.0.0</AssemblyVersion>
  </PropertyGroup>
  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
  <ItemGroup>
    <PackageReference Include="FluentValidation" Version="12.2.0" />
    <PackageReference Include="PAN.Mediator" Version="2.0.0" />
  </ItemGroup>
</Project>
Enter fullscreen mode Exit fullscreen mode

Those AssemblyTitle/Product properties used to live in AssemblyInfo.cs. That is the
tool's signature, and it is a good thing: less ceremony, same metadata.

What the tool could not do

The Upgrade Assistant does not migrate System.Web namespaces —
Microsoft's migration guide
is explicit about it. ASP.NET Core is a different hosting model, not a new version of Web API.

So I created a new project, Example.ApiCore (Microsoft.NET.Sdk.Web), moved the controller
over, and deleted the old host entirely:

Legacy (net48) Modern (net10)
Global.asax + App_Start (5 classes) One Program.cs
IDependencyResolver bridge (~50 lines) Built-in container
Controllers registered by reflection Registered automatically
Validators registered by reflection AddValidatorsFromAssemblyContaining<T>()
ConfigurationManager + env fallback IConfiguration
Web.config + transforms appsettings.json + user-secrets

The composition root is where the difference hurts most. Before, MediatorConfig built a
service provider manually, wired a custom dependency resolver, and replaced Web API's
exception handler by hand:

// Before: MediatorConfig.cs (excerpt)
ServiceProvider = services.BuildServiceProvider();

GlobalConfiguration.Configuration.DependencyResolver =
    new WebApiDependencyResolver(ServiceProvider);

GlobalConfiguration.Configuration.Services.Replace(
    typeof(IExceptionHandler),
    ServiceProvider.GetRequiredService<CustomExceptionHandler>());

// ...plus a foreach loop registering every IHttpController in DI
Enter fullscreen mode Exit fullscreen mode

After:

// After: Program.cs (excerpt)
builder.Services.AddPanMediator(config =>
{
    config.RegisterServicesFromAssembly(typeof(CreateCustomerUseCaseHandler).Assembly);
    config.AddOpenBehavior(typeof(ValidationBehavior<,>));
    config.AddOpenBehavior(typeof(LoggingBehavior<,>));
});

builder.Services.AddValidatorsFromAssemblyContaining<CreateCustomerCommandValidator>();
builder.Services.AddScoped<ICustomerRepository>(_ => new CustomerRepository(connectionString));

builder.Services.AddExceptionHandler<CustomExceptionHandler>();
builder.Services.AddProblemDetails();
builder.Services.AddControllers();

var app = builder.Build();
app.UseExceptionHandler();
app.MapControllers();
app.Run();
Enter fullscreen mode Exit fullscreen mode

Around 150 lines of plumbing across two files became roughly 15. The static
ServiceProvider property (a service locator in disguise) simply disappeared.

IExceptionHandler: same name, two worlds

This was my favourite trap. Both frameworks have an IExceptionHandler, but they are
different contracts:

// Web API 2: System.Web.Http.ExceptionHandling
public Task HandleAsync(ExceptionHandlerContext context, CancellationToken cancellationToken)

// ASP.NET Core: Microsoft.AspNetCore.Diagnostics
public ValueTask<bool> TryHandleAsync(HttpContext context, Exception exception, CancellationToken cancellationToken)
Enter fullscreen mode Exit fullscreen mode

Same name, different namespace, different signature, different wiring
(AddExceptionHandler<T>() + AddProblemDetails() + UseExceptionHandler() instead of
Services.Replace). If you migrate on autopilot, the compiler will tell you — but only
after you understand why.

The payoff: two custom classes were deleted.

  • My hand-rolled ProblemDetails → Microsoft.AspNetCore.Mvc.ProblemDetails.
  • My TraceLogger<T> adapter → the framework's real logging providers.

The final handler maps exceptions to RFC 7807 responses with a switch expression, and
traceId comes free from HttpContext.TraceIdentifier:

(string Detail, string Title, int StatusCode) = exception switch
{
    ValidationException => (exception.Message, nameof(ValidationException),
        StatusCodes.Status400BadRequest),
    BusinessException business => (business.Message, "Error de negocio",
        business.Status > 0 ? business.Status : StatusCodes.Status400BadRequest),
    _ => ("Ocurrió un error inesperado en nuestro sistema.", "Internal Server Error",
        StatusCodes.Status500InternalServerError)
};
Enter fullscreen mode Exit fullscreen mode

And those 8 <bindingRedirect> entries in Web.config? Gone. ASP.NET Core resolves
assembly versions at build time. No more DLL hell at runtime.

The proof: git says the core never changed

This is the part I am most proud of, and you can verify it yourself:

git diff master feature/migrate-to-net10 -- Example.UseCase Example.Dtos Example.Entities Example.Ports
# empty output
Enter fullscreen mode Exit fullscreen mode

The four use-case handlers, the DTOs, the entity, the repository port, the logging behaviour
and the CQRS contracts have identical blob hashes in both branches. Not "similar".
Identical.

Metric Before (net48) After (net10)
API project file ~14 KB ~1 KB (−93%)
Packages in the host 22 (packages.config) 3 (PackageReference)
Configuration 64-line Web.config, 8 binding redirects 12-line appsettings.json
DI plumbing ~150 lines ~15 lines
Custom infra classes TraceLogger, ProblemDetails deleted (built-in)
Domain/application files changed — 0

That is the hexagonal architecture paying for itself. The tool migrated my project files;
the architecture migrated my system.

Dependencies: the upgrade you didn't know you needed

Migrating the TFM also unlocked versions I could not use before:

  • FluentValidation 11.12.0 → 12.2.0. Version 12 dropped netstandard2.0 support, so net48 silently pinned me to 11.x. Your legacy TFM does not just age your runtime — it ages your whole dependency tree.
  • System.Data.SqlClient → Microsoft.Data.SqlClient 7.1.2. Classic gotcha: encryption is on by default since 4.0, so local connections need TrustServerCertificate=True (or a proper certificate). My connection string already had it, but plan for this.
  • Dapper 2.0.78 → 2.1.89.
  • PAN.Mediator 2.0.0 and PAN.DapperLambdaSQL 1.3.0: unchanged. Both target netstandard2.0, so they run on net48 and net10 without recompiling. If you maintain libraries, this is the argument for netstandard2.0 in one sentence.

Bonus: the modern host got Swagger (Swashbuckle) in development — something the legacy
API never had.

Lessons learned

  1. Rewrites lose defensive details. My legacy handler had a guard: Status > 0 ? ... : BadRequest, because BusinessException leaves Status = 0 when constructed with just a message. My first migrated version dropped it — and a BusinessException("msg") would have set StatusCode = 0 and thrown inside the exception handler. A post-migration review caught it. Compilation is not behavioural equivalence: diff the old code against the new, line by line.
  2. Polish the REST details while you are there. Created(string.Empty, result) became CreatedAtAction(nameof(Single), new { id = result.Id }, result) — a real Location header instead of an empty one.
  3. Secrets leave the repo. The legacy Web.config had a database password in plain text. Now the connection string lives in user-secrets / environment variables, and appsettings.json ships empty. Rotate anything that ever touched source control.
  4. Be honest about trade-offs. Example.BuildingBlocks now takes a FrameworkReference to Microsoft.AspNetCore.App (it used to reference System.Web.Http). A purist would move the exception handler into the host; I keep it centralised for reuse. Know which rules you are bending and why.

Closing

The whole migration took a few hours of manual work on top of the tool's output, and the
risk was low because the core was already isolated. If your domain is coupled to
System.Web, no tool will save you. If it is not, the tool plus a new host is enough.

The repo, with both branches so you can diff the whole thing:

👉 https://github.com/PedroAvila/LegacyProject

If you are planning a similar migration, start by asking one question: how much of my code
would survive if I deleted the host today?
That number is your real migration cost.

Top comments (0)