Microsoft ended mainstream support for .NET Framework 4.x and made clear that .NET 5 — built on the .NET Core lineage — is the unified platform going forward. Applications that remain on .NET Framework 4.5 cannot simply recompile against .NET 5; they require deliberate refactoring through .NET Core 3.1 as an intermediate target. The Legacy Cycle Store modernization series walks through exactly that journey, starting from a running ASP.NET MVC 4 / Entity Framework 5 application and ending with a containerized ASP.NET Core workload ready for AWS.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/aws-samples/legacy-cycle-store-mvc-app/llms.txt
Use this file to discover all available pages before exploring further.
The Challenge
.NET Framework and .NET Core share a language (C#) and many runtime concepts, but they are distinct platforms with incompatible hosting models, configuration systems, and dependency injection frameworks. Moving from one to the other is not a tooling upgrade — it is a controlled migration with several well-known breaking changes:- ASP.NET MVC 4 relies on
System.Web, which does not exist in .NET Core. Controllers, filters, HTTP modules, and HTTP handlers must all be replaced with their ASP.NET Core equivalents. - Entity Framework 5 Database-First EDMX generates code from T4 templates and stores model metadata in XML. EF Core has no EDMX concept; the migration requires replacing auto-generated files with hand-authored Code-First entity classes and a new
DbContext. - Configuration moves from
Web.config(XML, with transform files per environment) toappsettings.jsonplus environment variables, which aligns naturally with container deployments. - Application startup moves from
Global.asaxand static configuration classes toProgram.csandStartup.cs, with a built-in dependency injection container available from the start.
Three-Phase Approach
Run the Legacy App (Part 1 — this repository)
Deploy the
CYCLE_STORE SQL Server database on Amazon RDS using the provided CloudFormation template, then configure and run the ASP.NET MVC 4 / EF5 application locally against that database. The goal of Part 1 is to understand the starting state in full: the EDMX model, the CYCLE_STOREEntities DbContext, the CategoryManager and ProductManager business classes, and how the MVC controllers wire everything together. You cannot modernize what you do not understand.Migrate to .NET Core (Part 2)
Replace the EDMX Database-First model with EF Core Code-First entity classes and a new
CycleStoreContext. Migrate the ASP.NET MVC 4 controllers and views to ASP.NET Core 3.1 MVC, replacing System.Web dependencies throughout. Update dependency injection so that CategoryManager and ProductManager receive CycleStoreContext via constructor injection rather than instantiating it directly. Move configuration from Web.config to appsettings.json. Replace Global.asax startup logic with Program.cs and Startup.cs.Containerize (Part 3)
Package the modernized ASP.NET Core application in a multi-stage Docker image using the official Microsoft base images. Push the image to Amazon Elastic Container Registry (ECR). Deploy to AWS using the container service of your choice — Amazon ECS on Fargate, Amazon EKS, or AWS App Runner. Pass the RDS connection string as an environment variable at runtime so the image itself contains no credentials.
What Changes
The following table summarises the concrete technology substitutions made across the three phases:| Legacy (.NET Framework 4.5) | Modernized (.NET Core 3.1+) |
|---|---|
ASP.NET MVC 4 (System.Web.Mvc) | ASP.NET Core MVC (Microsoft.AspNetCore.Mvc) |
| Entity Framework 5 EDMX (Database-First) | EF Core Code-First (Microsoft.EntityFrameworkCore) |
Web.config + XML transforms | appsettings.json + environment-specific overrides |
Global.asax + RouteConfig / FilterConfig | Program.cs + Startup.cs |
packages.config NuGet references | <PackageReference> in SDK-style .csproj |
| IIS / Windows-only hosting | Cross-platform Kestrel hosting, Docker-ready |
Static DbContext instantiation in managers | Constructor dependency injection via built-in DI container |
| T4-generated partial entity classes | Hand-authored POCO entity classes |
What Stays the Same
The migration is extensive but not a rewrite. The following artifacts carry over with little or no modification:- C# business logic in
CategoryManagerandProductManager— the LINQ queries and method signatures remain identical. - Razor views (
.cshtml) — the Razor syntax is compatible between MVC 4 and ASP.NET Core MVC. The main exception is@{Html.RenderAction(...)}child action calls, which require replacement with View Components. - SQL Server database schema — the
CYCLE_STOREdatabase on RDS is not touched during the migration. EF Core maps to the sameProductionschema tables. - MVC routing conventions — the
{controller}/{action}/{id}default route pattern is identical in both frameworks. - Model binding and validation — data annotations (
[Required],[StringLength], etc.) and model binding work the same way in ASP.NET Core MVC.
.NET Core 3.1 is a Long-Term Support (LTS) release supported until December 2022. The modernization targets 3.1 as the minimum viable Core version because it is the last release before .NET 5 unified the platform. After completing this migration series, upgrading from 3.1 to .NET 5 (or later) is a straightforward
<TargetFramework> bump with only minor API adjustments — a far smaller effort than the initial Framework-to-Core move.Explore the Migration Steps
EF to EF Core
Replace the EDMX Database-First model with EF Core Code-First entity classes and a modern
DbContext.ASP.NET to Core
Migrate controllers, startup, routing, and Razor views from ASP.NET MVC 4 to ASP.NET Core 3.1.
Containerization
Package the modernized app in Docker and push to Amazon ECR for deployment on AWS.
Introduction
Return to the series introduction and learn how to run the legacy app against Amazon RDS.