Skip to main content
Optimizely Academy

End-user eLearning

Upcoming events

Certification

Partner training

Community

All Topics

Code refactoring

  • By Optimizely Education
  • Published: Mar 3, 2026
  • Rating
    Average rating: 0 No reviews

Outline
At a glance:
  • Upgrade is not modernization: The Upgrade Assistant handles mechanics, not architecture.
  • Major shift: Moving from ASP.NET Framework to ASP.NET Core requires structural refactoring.
  • Key focus areas: Dependency Injection, middleware, routing, and configuration changes.
  • Templates advantage: dotnet new templates provide a clean, best-practice foundation.

This module explores two critical aspects of preparing CMS 11 solutions for CMS 12: comprehensive code refactoring and the strategic use of new project templates. While the Upgrade Assistant provides a strong starting point, meaningful modernization requires deliberate architectural changes aligned with ASP.NET Core principles.

The Necessity of Code Refactoring for CMS 12

Migrating to CMS 12 involves more than upgrading NuGet packages. It requires aligning your solution with ASP.NET Core architecture and Optimizely's updated APIs.

Beyond the Upgrade Assistant

  • Adopt ASP.NET Core Idioms: Embrace Dependency Injection, middleware, and appsettings.json.
  • Remove System.Web Dependencies: Replace legacy types with ASP.NET Core equivalents.
  • Modernize MVC: Update controllers, filters, model binding, and view components.
  • Optimize Performance: Prefer async/await and efficient I/O patterns.

Common Refactoring Tasks

The most impactful change for most solutions is replacing the Service Locator pattern with constructor-based Dependency Injection.

C#
// CMS 11 (old pattern) // var myService = ServiceLocator.Current.GetInstance<IMyService>(); // CMS 12 (constructor injection) public class MyController : Controller { private readonly IMyService _myService; public MyController(IMyService myService) { _myService = myService; } public IActionResult Index() { _myService.DoSomething(); return View(); } }

Additional refactoring areas to address across the solution:

Refactoring areas

Select a topic to expand and read the details.

HttpContext and Routing ▼
  • HttpContext Changes: Replace HttpContext.Current with injected IHttpContextAccessor or controller access.
  • Routing Updates: Use Endpoint Routing instead of legacy route configuration.
Configuration and URL Rewrites ▼
  • URL Rewrite Migration: Move rules from web.config to middleware or IIS rewrite modules.
  • Content Providers: Re-implement using ASP.NET Core file providers.
Startup and Initialization ▼

Initialization Modules: CMS 11 IInitializableModule implementations need to align with the ASP.NET Core startup lifecycle, typically moving logic into Program.cs service registration or hosted services.

Note: The Upgrade Assistant cannot detect all uses of HttpContext.Current or Service Locator patterns in third-party dependencies. Audit your full dependency graph before declaring the migration complete.

Leveraging New Project Templates

Optimizely provides modern dotnet new templates that accelerate CMS 12 and Commerce 14 development using best practices.

Why Use the Templates?

  • Clean Foundation: Pre-configured ASP.NET Core and Optimizely setup with no legacy baggage.
  • Best Practices Built-In: DI, structured logging, and modern configuration are wired up from day one.
  • Available Options: epi-cms-empty, epi-cms-alloy, epi-commerce-empty, epi-commerce-alloy.

Installing the Templates

Bash
dotnet new install EPiServer.Net.Templates

Creating a New Project

Bash
dotnet new epi-cms-alloy --name MyNewOptimizelySite

Migration Strategies Using Templates

  • Rebuild Strategy: Start fresh from a template and migrate content and data across to the new solution.
  • Strangler Pattern: Gradually migrate modules into a new template-based solution alongside the running legacy system.
  • Learning Tool: Templates demonstrate correct CMS 12 structure and configuration - ideal for onboarding developers unfamiliar with the new platform.

Pro tip: Even if you're upgrading an existing solution rather than rebuilding, scaffold a fresh template project and use it as a reference implementation. Comparing your startup configuration, DI registration, and middleware pipeline against the template reveals most of the structural gaps quickly.

Conclusion

Successful migration from CMS 11 to CMS 12 requires intentional refactoring beyond automated tools. By adopting ASP.NET Core best practices and strategically leveraging modern project templates, teams can modernize - not just upgrade - their Optimizely solutions, ensuring long-term maintainability, scalability, and performance.