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 customProblemDetails, and 8 binding redirects. - My own
netstandard2.0NuGet 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
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 tinyTraceLoggeradapter overSystem.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.configwithPackageReference. - Changed the target framework to
net10.0. - Moved
AssemblyInfo.csattributes into MSBuild properties (all sevenAssemblyInfo.csfiles 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>
<!-- 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>
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
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();
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)
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)
};
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
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.SqlClient7.1.2. Classic gotcha: encryption is on by default since 4.0, so local connections needTrustServerCertificate=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
-
Rewrites lose defensive details. My legacy handler had a guard:
Status > 0 ? ... : BadRequest, becauseBusinessExceptionleavesStatus = 0when constructed with just a message. My first migrated version dropped it — and aBusinessException("msg")would have setStatusCode = 0and 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. -
Polish the REST details while you are there.
Created(string.Empty, result)becameCreatedAtAction(nameof(Single), new { id = result.Id }, result)— a realLocationheader instead of an empty one. -
Secrets leave the repo. The legacy
Web.confighad a database password in plain text. Now the connection string lives in user-secrets / environment variables, andappsettings.jsonships empty. Rotate anything that ever touched source control. -
Be honest about trade-offs.
Example.BuildingBlocksnow takes aFrameworkReferencetoMicrosoft.AspNetCore.App(it used to referenceSystem.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:
- Legacy (net48):
master - Migrated (net10):
feature/migrate-to-net10 - Full diff: https://github.com/PedroAvila/LegacyProject/compare/master...feature/migrate-to-net10
👉 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)