migrate-dotnet-framework

Migrate .NET Framework to .NET 10

When to use

• The project targets .NET Framework 4.x (see legacy/dotnet-framework) and the user wants to move to .NET 10 LTS.
• A component must leave .NET Framework (Windows-only hosting, 4.6.2 ending 12 Jan 2027, a library that dropped Framework support).

For servicing only, keep the app on 4.8/4.8.1 and patch Windows; this skill is for migration.

Before you start

• Assess and write the results to docs/netfx-assessment.md or the PR:
  • solution structure: project types (Web Forms, MVC 5, Web API 2, WCF service/client, ASMX, WinForms/WPF, Windows service, class libraries), TFMs, packages.config vs PackageReference;
  • System.Web usage outside the web project (HttpContext.Current in libraries is the usual blocker);
  • WCF bindings and behaviors in use (CoreWCF supports common HTTP and NetTcp bindings, not every WS-* feature);
  • packages and their .NET support; Windows-only APIs (registry, WMI, COM, System.Drawing on servers, AppDomains, Remoting, Code Access Security) that need replacements.
• Ask the user:
  • target (default .NET 10 LTS) and approach (default incremental/strangler, not a rewrite);
  • whether a reverse proxy can sit in front of the old app;
  • whether package installs are approved (core/supply-chain);
  • whether GitHub Copilot upgrade may be used for assessment and code changes (needs a GitHub Copilot subscription and sends code to Copilot models). The steps below work without it.
• Working tree clean; new branch; build and tests pass on the Framework app (record failures).

Steps

1. Characterization tests: HTTP-level tests for key pages and endpoints, contract tests for WCF/ASMX operations (sample requests and expected responses), runnable against old and new implementations.
2. Libraries first: convert class libraries to SDK-style projects, then to netstandard2.0 or net48;net10.0; move System.Web and config access (ConfigurationManager) behind interfaces so both hosts can supply them.
3. New host: an ASP.NET Core (.NET 10) app becomes the entry point. Add YARP to proxy every route not yet migrated to the Framework app, and System.Web adapters (Microsoft.AspNetCore.SystemWebAdapters packages) for remote session and remote authentication with the Framework app.
4. Port incrementally:
   • MVC 5 / Web API 2 controllers → ASP.NET Core controllers (similar model; filters, model binding and DI change);
   • Web Forms pages → Razor Pages or Blazor (a rewrite of the UI; the Copilot upgrade Web Forms-to-Blazor scenario can help);
   • ASMX services → CoreWCF or ASP.NET Core endpoints keeping the same contract;
   • Global.asax, HTTP modules and handlers → middleware. Route one area at a time: port, run the characterization tests against the new host, then remove the YARP fallback for that route.
5. WCF services: host contracts with CoreWCF (current 1.9) on .NET 10, keeping bindings clients rely on; configure security (transport TLS, auth) explicitly; plan gRPC or HTTP APIs for new clients. WCF clients use the System.ServiceModel.Http/.NetTcp packages.
6. Config and secrets: Web.config app settings and connection strings → appsettings.json plus environment variables or a secret store; machine keys → ASP.NET Core Data Protection (with a shared key ring if cookies must be read by both apps during the transition).
7. Retire: when the proxy no longer forwards anything, remove the Framework app and the System.Web adapter remote features.
8. Show each step's diff and test results; wait for approval before switching routes. Commit only when asked (git-commit skill). Then switch to backend/aspnet-core and languages/csharp.