Skill v1.0.0

currentTrusted Publisher100/100

microsoft/microhack/dotnet-upgrade

──Details

PublishedOctober 10, 2026 at 11:04 AM

Content Hashsha256:2425ea89f7affef9...

Git SHA

──Files

Files (1 file, 3.2 KB)

SKILL.md3.2 KBactive

SKILL.md · 73 lines · 3.2 KB

version: "1.0.0" 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)

powershell

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)

All versions