| name | dotnet-upgrade |
| description | Transformation rules and verification steps for upgrading .NET Framework 4.x applications to .NET 9. WHEN: upgrade to .NET 9, migrate .NET Framework, retarget TFM, convert to SDK-style project, System.Web replacement, web.config migration, packages.config to PackageReference, binding redirect cleanup. NOT for: greenfield .NET apps, NuGet version bumps within the same TFM, Azure infrastructure changes. |
.NET Framework 4.x → .NET 9 Upgrade Rules
Purpose
Packages the API mappings, project-file rules, and verification checklist needed to
retarget a .NET Framework app to .NET 9 without behavioral change.
Prerequisites
ASSESSMENT.md exists and is approved (AppCAT findings available).- .NET 9 SDK installed — verify:
dotnet --list-sdks.
Procedure
Step 1 — Convert to SDK-style projects (leaf projects first)
dotnet tool install -g upgrade-assistant
upgrade-assistant upgrade .\src\{{Project}}.csproj
- Migrate
packages.config → PackageReference.
- Delete
AssemblyInfo.cs attributes now generated by the SDK.
- Remove binding redirects from app/web.config (not honored on .NET 9).
Step 2 — Apply API transformation rules
| Source pattern (.NET Framework) | Target pattern (.NET 9) | Notes |
|---|
System.Web.Mvc controllers | Microsoft.AspNetCore.Mvc | Routing moves to endpoint routing |
Global.asax / HttpModule | ASP.NET Core middleware in Program.cs | Order matters — replicate pipeline order |
web.config appSettings | appsettings.json + IConfiguration | Keep keys identical to limit churn |
ConfigurationManager.AppSettings | IConfiguration via DI | Inject, don't service-locate |
HttpContext.Current | IHttpContextAccessor | Audit for thread-safety assumptions |
WCF server (System.ServiceModel) | CoreWCF or gRPC/REST | Decision required — escalate to user |
EF6 ObjectContext/EDMX | EF Core (or EF6 on .NET 9 as interim) | EDMX must be re-scaffolded for EF Core |
System.Drawing (non-Windows) | ImageSharp / SkiaSharp | System.Drawing.Common is Windows-only |
| {{APP_SPECIFIC_RULE_1}} | {{TARGET_1}} | {{NOTE}} |
| {{APP_SPECIFIC_RULE_2}} | {{TARGET_2}} | {{NOTE}} |
Step 3 — Verify
Common Pitfalls
- ⚠️ Upgrading hub projects first — always go leaf-first in the dependency graph, or you'll chase cascading build breaks.
- ⚠️
AppContext switches / legacy config quirks silently ignored on .NET 9 — search config for <runtime> elements and review each.
- ⚠️ Culture-sensitive string APIs changed defaults (ICU vs NLS) — pin
InvariantGlobalization consciously, don't copy-paste it.
- ⚠️ {{APP_SPECIFIC_PITFALL}}
References
- Microsoft Learn: "Upgrade from .NET Framework" / breaking changes by version
- AppCAT rule documentation (linked from
ASSESSMENT.md findings)
