Choosing an ASP.NET Framework

ASP.NET is documented here as three separate lineages — ASP.NET Web Forms, ASP.NET MVC (Razor), and ASP.NET Core (Blazor) — each with its own runtime, package set, and support status. This page spans more than one lineage; see each sub-section’s own landing page for its specific version and support-status disclaimer.

This content was generated with the assistance of AI and should be verified against the official documentation linked throughout before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

The Evolution of ASP.NET explains how ASP.NET Web Forms, ASP.NET MVC (Razor) and ASP.NET Core (Blazor) came to exist as three separate lineages. This page is the practical follow-up: which one should a given project actually use.

Green-field: always ASP.NET Core

If there is no existing System.Web codebase to consider, the answer is unconditional: build on ASP.NET Core, targeting the current .NET LTS release. It is the only lineage that is cross-platform, actively developed, and has a supported forward path for the lifetime of the application. Neither ASP.NET Web Forms nor ASP.NET MVC 5 should be chosen for a new project under any circumstance — both are functionally frozen and receive security fixes only.

flowchart TD Start{Existing System.Web app?} Start -->|No| Core[Build on ASP.NET Core] Start -->|Yes| Which{Which lineage?} Which -->|Web Forms| WF{Can it be rewritten\nor is it long-lived?} Which -->|MVC 5 / Web API 2| MVC{How much .NET-Framework-only\nsurface remains?} WF -->|Long-lived, low churn| KeepWF[Keep on .NET Framework 4.8.1,\nsecurity fixes only] WF -->|Actively developed| MigrateWF[Incremental migration:\nSystem.Web.Adapters + YARP] MVC -->|Little/none| MigrateMVC[Migrate with the\n.NET Upgrade Assistant] MVC -->|A lot: WebParts, OWIN-only\nauth, sync-heavy code| Hybrid[Side-by-side with YARP,\nmigrate page by page] MigrateWF --> Core MigrateMVC --> Core Hybrid --> Core

An existing Web Forms codebase

Keep it running on .NET Framework 4.8.1 for as long as it needs to exist, budgeting only for security patching and dependency updates — Web Forms itself never shipped on .NET Core/.NET 5+ and never will. When change is actually needed:

  • For an application that is stable and rarely touched, the lowest-risk choice is to leave it exactly where it is.

  • For an application under active development, Migrating to Modern ASP.NET covers the incremental path — running the legacy app and a new ASP.NET Core app side-by-side behind YARP, sharing session/auth via System.Web.Adapters, and cutting pages over one at a time — plus why Blazor Server is usually the closest conceptual landing spot for a control-tree, event-driven UI.

An existing MVC 5 / Web API 2 codebase

MVC 5 is architecturally closer to ASP.NET Core than Web Forms is (both are pattern-based, controller/action oriented), which makes a full migration more tractable:

  • The .NET Upgrade Assistant automates much of the mechanical work (project-file conversion, common API substitutions) for applications with limited System.Web-only surface.

  • For larger applications, the same incremental System.Web.Adapters + YARP approach used for Web Forms applies here too — see Migrating to ASP.NET Core for the concrete MVC 5 → ASP.NET Core mapping table.

Pieces with no forward path

Some System.Web-era APIs have no direct ASP.NET Core equivalent — they must be redesigned, not translated:

No forward path Replace with

System.Web (HttpContext.Current, HttpContextBase)

HttpContext via DI (IHttpContextAccessor only where DI genuinely cannot reach it)

ViewState

Explicit state: query string, TempData/session, or client-side state in Blazor (see Blazor State Management)

HttpModule / HttpHandler

ASP.NET Core middleware (Request Pipeline and Middleware)

Web Forms server controls (GridView, Repeater, Web Parts, user/custom controls)

Razor components (Blazor) or Tag Helpers + partial views (MVC/Razor Pages)

ASMX web services / WCF server

ASP.NET Core Web API controllers or gRPC services (gRPC)

Membership/Role/Profile providers

ASP.NET Core Identity (Authentication and ASP.NET Core Identity)

web.config (<appSettings>, <connectionStrings>, custom sections)

appsettings.json + the options pattern (Configuration and the Options Pattern)

Web Forms → MVC 5 → ASP.NET Core: a concept map

Web Forms MVC 5 ASP.NET Core

Page life cycle (Page_Load, …​)

Action method

Endpoint / action / OnGet/OnPost

.aspx + code-behind

Razor view (.cshtml) + controller

Razor view/component (.cshtml/.razor)

ViewState

TempData / ViewBag

Explicit state / [PersistentState] (Blazor)

Server control (asp:GridView)

HTML helper (Html.DisplayFor)

Tag Helper / Razor component

web.config provider model

OWIN middleware + Identity 2

ASP.NET Core middleware + Identity

Postback (__doPostBack)

Full-page HTTP request

HTTP request, or a Blazor circuit/WASM render

Each cell links to the page that documents it in depth: start from ASP.NET Web Forms, ASP.NET MVC (Razor) or ASP.NET Core (Blazor) and follow the cross-links from there — migrating-…​ pages in each sub-section go into the mechanics this table only summarizes.