25 Steps to Migrate Old MVC Project to ASP.NET Core 10

Most .NET developers eventually face the desire, or even the necessity, to migrate old MVC project or their applications to ASP.NET Core. The benefits are clear: improved performance, cross-platform compatibility, a modern development experience, and access to the latest features. However, the path to a successful migration is often fraught with peril. A rushed or poorly planned upgrade can lead to broken authentication, routing nightmares, and catastrophic data access issues, resulting in significant downtime and developer headaches.

But what if there was a proven, step-by-step approach to safely and efficiently transition your legacy MVC application to the latest ASP.NET Core? This guide outlines a comprehensive 25-step plan designed to minimize risks, ensure continuity, and set your team up for long-term success. Let’s dive in!

The Migration Journey: A Step-by-Step Blueprint

Phase 1: Planning and Preparation

1. Define why you need the upgrade and what success looks like. Before writing a single line of code, clearly articulate the “why.” Are you seeking performance gains, cloud readiness, cross-platform deployment, or a modern developer experience? Defining success metrics (e.g., reduced load times, improved scalability, easier maintenance) will guide your decisions throughout the process.
2. List all apps, projects, and dependencies. Gain a complete inventory of your current ecosystem. Map out all applications, their interdependencies, third-party libraries, and external services. This includes database connections, API integrations, and any unique infrastructure components. A visual dependency graph can be incredibly helpful here.

Phase 2: Implementing the Strangler Fig Pattern

3. Use the Strangler Fig pattern. This architectural pattern is your best friend for large migrations. Instead of a “big bang” rewrite, you gradually replace specific functionalities of the old system with new ones in your ASP.NET Core application, routing traffic incrementally. This allows for continuous delivery and minimizes risk.
4. Create a new ASP.NET Core app in a separate solution. Start fresh! Set up a new, clean ASP.NET Core project. This provides a clean slate and avoids cluttering your existing solution with migration-related code.
5. Set up a YARP reverse proxy in front of both apps. YARP (Yet Another Reverse Proxy) will act as the gatekeeper, intelligently routing requests to either your old MVC app or your new ASP.NET Core app. This is crucial for the Strangler Fig pattern, as it allows you to shift traffic gradually.

Phase 3: Initial Code Upgrades and Modernization

6. Run .NET Upgrade Assistant. Leverage Microsoft’s .NET Upgrade Assistant. This tool can automate many common migration tasks, helping you update project files, NuGet packages, and even some code constructs. It’s a fantastic starting point, but it won’t do everything.
7. Upgrade class libraries to .NET Standard. If you have shared class libraries, migrate them to .NET Standard. This ensures they can be referenced by both your legacy .NET Framework application and your new ASP.NET Core application, facilitating code reuse during the transition.
8. Update project files to SDK style and fix NuGet package versions. Embrace the simplified SDK-style project files. This makes managing dependencies and project configurations much easier. Standardize your NuGet package versions across all projects to avoid conflicts.
9. Migrate EF6 to EF Core. Entity Framework 6 is not directly compatible with ASP.NET Core. You’ll need to migrate your data access layer to Entity Framework Core. This is a significant undertaking, often requiring schema changes and code adjustments.
10. Use Dapper instead of ADO.NET for heavy database reads. For performance-critical database read operations, consider using Dapper. It’s a lightweight ORM that offers significant speed advantages over raw ADO.NET or even EF Core for specific scenarios.
11. Move configuration to appsettings.json. ASP.NET Core’s configuration system is vastly improved. Migrate your configuration (connection strings, application settings) from web.config to appsettings.json and leverage the IConfiguration interface.
12. Port cross-cutting concerns. Identify and port common functionalities like logging, caching, and error handling. ASP.NET Core uses middleware and filters for many of these concerns, offering a more modular and flexible approach.

Phase 4: Feature-by-Feature Migration

13. Recreate authentication and authorization. This is often one of the most complex parts of the migration. ASP.NET Core Identity is the recommended approach. Carefully plan how to migrate user accounts, roles, and claims from your existing authentication system.
14. Move static files to wwwroot. ASP.NET Core serves static files (CSS, JavaScript, images) from the wwwroot folder by default. Consolidate your static assets into this directory in your new application.
15. Migrate one MVC controller end-to-end. Pick a small, low-risk controller or feature. Migrate its views, actions, models, and associated logic to ASP.NET Core. This allows you to validate your migration strategy on a smaller scale.
16. Verify and fix fast. Thoroughly test the migrated controller. Unit tests, integration tests, and manual testing are crucial here. Identify and fix any issues immediately to maintain momentum and confidence.
17. Repeat this process for the next controller or feature. Once you’ve successfully migrated and validated one component, move on to the next. The Strangler Fig pattern allows you to iteratively migrate features without disrupting the entire application.

Phase 5: Modernizing and Optimizing

18. Replace HttpModules and DelegatingHandlers with middleware or filters. ASP.NET Core’s middleware pipeline is a powerful and flexible way to handle requests. Replace your old HttpModules and DelegatingHandlers with modern middleware components or action filters.
19. Add health checks, metrics, and structured logging from the start. Don’t wait until production to implement observability. Integrate health checks, performance metrics (e.g., using Prometheus), and structured logging (e.g., Serilog or NLog) early in the process.
20. Set up CI/CD pipelines. Automate your build, test, and deployment processes. A robust CI/CD pipeline ensures consistent deployments, faster feedback, and reduces the risk of human error.
21. Run integration, load, and security tests. Beyond unit tests, conduct comprehensive integration tests to ensure all components work together seamlessly. Perform load tests to verify performance under expected traffic and security tests to identify vulnerabilities.

Phase 6: Cutover and Post-Migration

22. Switch most traffic to ASP.NET Core while keeping a way to roll back. Gradually increase the percentage of traffic routed to your new ASP.NET Core application using your YARP proxy. Always maintain a quick and reliable rollback mechanism in case unexpected issues arise.
23. Remove old routes that are fully moved and working well. As features are fully migrated and proven stable in ASP.NET Core, decommission the corresponding routes and code from your old MVC application. This cleans up the legacy system.
24. Upgrade remaining libraries to .NET. Once the core migration is complete, identify any remaining third-party libraries that can be upgraded to their .NET Core compatible versions. This will further modernize your stack.
25. Write down new patterns, commands, and guides for your team. Document everything! Create internal guides, best practices, and code examples for your team. This ensures consistency, simplifies onboarding, and prevents knowledge silos as you embrace the new ASP.NET Core environment.

 
Migrating an old MVC project to ASP.NET Core is a significant undertaking, but by following these 25 steps, you can navigate the process with confidence, minimize risks, and unlock the full potential of a modern, high-performance application. Happy migrating!

Migrate Old MVC Project