Skip to main content
Optimizely Academy
End-user eLearning
Events
Certification
Partner training
Community
All Topics

Upgrade Assistant

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

Outline
At a glance
  • Purpose: Automates mechanical upgrade steps from CMS 11 (.NET Framework) to CMS 12 (.NET 6+ / ASP.NET Core).
  • Type: .NET CLI global tool that analyzes and transforms projects.
  • Helps with: Project file conversion, package updates, configuration migration, and common API changes.
  • Does NOT handle: Complex refactoring, third-party upgrades, front-end changes, or full breaking-change resolution.
  • Best approach: Use iteratively with version control and thorough testing.

This module introduces the Optimizely Upgrade Assistant, a crucial tool designed to streamline the migration process from Optimizely CMS 11 (based on ASP.NET Framework) to CMS 12 (based on ASP.NET Core). Understanding its capabilities and limitations is essential for development teams aiming for an efficient and low-risk transition.

What is the Optimizely Upgrade Assistant?

The Optimizely Upgrade Assistant is a .NET CLI global tool that automates repetitive and mechanical migration tasks when upgrading a CMS 11 solution to CMS 12. It provides a structured starting point by performing common project and code transformations.

  • Purpose: Assists developers in porting CMS 11 projects to the ASP.NET Core-compatible structure and APIs required by CMS 12.
  • Nature: Command-line tool that analyzes existing project files and source code, applying predefined transformations.

How to Use the Upgrade Assistant

1. Prerequisites

  • .NET SDK: Install a compatible SDK (e.g., .NET 6 or higher).
  • CMS 11 Solution: Ensure the project compiles successfully before upgrading.
  • Backup: Always create a full backup before running the tool.

2. Installation

dotnet tool install -g EPiServer.DotNet.Cli.UpgradeAssistant

If already installed, update to the latest version:

dotnet tool update -g EPiServer.DotNet.Cli.UpgradeAssistant

3. Running the Assistant

Navigate to the root directory of your CMS 11 solution (where the .sln file resides). 

dotnet-episerver-upgrade-assistant upgrade
  • Interactive Mode: Prompts for confirmation and options during execution.
  • Target Scope: Can upgrade individual projects or the entire solution.

Scope and Limitations

What It Does

  • Project File Updates:
    • Converts .csproj files to SDK-style format.
    • Updates TargetFramework (e.g., net6.0, net8.0).
    • Updates NuGet packages to ASP.NET Core-compatible equivalents.
    • Removes redundant references.
  • Configuration Migration: Assists moving settings from web.config to appsettings.json.
  • Code Transformations:
    • Namespace updates (e.g., System.Web replacements).
    • Common API updates.
    • Startup/Program configuration adjustments.
    • Adds required using statements.
  • Structure Adjustments: Aligns projects with ASP.NET Core conventions.

What It Does NOT Do

  • Complex Refactoring: Does not re-architect custom solutions.
  • All Breaking Changes: Manual resolution required for advanced scenarios.
  • Third-Party Integrations: Libraries and add-ons must be manually reviewed.
  • Front-End Code: Does not update JavaScript, CSS, or legacy Web Forms components.
  • Content/Data Migration: Not a database migration or validation tool.
  • Performance Optimization: Manual profiling and refactoring required.

Best Practices

  • Clean CMS 11 Baseline: Ensure no warnings or build errors before upgrading.
  • Use Version Control: Create a dedicated migration branch.
  • Iterative Execution: Run, review, fix, and repeat.
  • Thorough Testing: Perform unit, integration, UI, and regression testing.
  • Consult Documentation: Use official migration guides alongside the tool.
  • Review Warnings Carefully: Warnings typically indicate manual follow-up work.

Conclusion

The Optimizely Upgrade Assistant significantly accelerates the initial phase of migrating CMS 11 to CMS 12 by automating mechanical transformations. However, it is not a full automation solution. Successful migration requires manual refactoring, comprehensive testing, and careful validation to achieve a stable, production-ready ASP.NET Core-based implementation.