Code refactoring

By Optimizely Education
Published: Mar 3, 2026
Rating 1 star 2 stars 3 stars 4 stars 5 stars

Average rating: 0 No reviews

Outline

At a glance

Upgrade ≠ 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.

1. 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.

2. Common Refactoring Tasks

Refactoring Service Locator to Dependency Injection

// 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();
    }
}
    

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

Leveraging New Project Templates

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

1. Why Use the Templates?

Clean Foundation: Pre-configured ASP.NET Core + Optimizely setup.
Best Practices Built-In: DI, structured logging, modern configuration.
Available Options: epi-cms-empty, epi-cms-alloy, epi-commerce-empty, epi-commerce-alloy.

2. Installing the Templates

dotnet new install EPiServer.Net.Templates
    

3. Creating a New Project

dotnet new epi-cms-alloy --name MyNewOptimizelySite
    

Rebuild Strategy: Start fresh and migrate content/data.
Strangler Pattern: Gradually migrate modules into a new template-based solution.
Learning Tool: Templates demonstrate correct CMS 12 structure and configuration.

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.