dotnet-upgrade

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

• dotnet build zero errors across the solution
• No remaining <TargetFramework>net4*</TargetFramework> (grep the repo)
• No references to System.Web outside compat shims
• Tests pass: dotnet test
• CVE scan clean of criticals (appmod-dotnet-cve-check)

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)