Skip to main content
Optimizely Academy

End-user eLearning

Upcoming 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 analyses 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 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 analyses existing project files and source code, applying predefined transformations.

How to use the Upgrade Assistant

1. Prerequisites

  • .NET SDK: Install a compatible SDK (.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

Install the tool globally via the .NET CLI:

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

If already installed, update to the latest version:

Bash
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) and run:

Bash
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 the tool handles - and what it doesn't

Select a topic to expand and read the details.

What it does - project files, configuration, and code transformations ▼
  • 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, and 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, and required using statement additions.
  • Structure adjustments: Aligns projects with ASP.NET Core conventions.
What it does NOT do - manual work still required ▼
  • 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 and data migration: Not a database migration or validation tool.
  • Performance optimisation: Manual profiling and refactoring still 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 after each iteration.
  • Consult documentation: Use official migration guides alongside the tool.
  • Review warnings carefully: Warnings typically indicate manual follow-up work.

Pro tip: Commit after each successful run of the assistant before making manual changes. This gives you a clean diff between automated and manual work, making review and rollback far easier.

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.