Upgrade to CMS 13 from CMS 12
Upgrade your Optimizely CMS solution from CMS 12 to CMS 13. This article covers the migration strategy, including AI-powered tools that streamline modernization.
For details about CMS 13 platform changes and upgrade considerations, see CMS 13 breaking changes.
🚧 Important CMS 13 runs on .NET 10 and newer. When upgrading from earlier CMS versions, ensure that your solution targets the required .NET version before beginning the migration.
Previous migration tools for Optimizely CMS have been deprecated. Microsoft recommends using GitHub Copilot or similar AI-assisted development tools to help modernize and update your codebase during the upgrade process.
Review mandatory components for CMS 13
Before starting, review Overview of CMS 13 to understand the mandatory and optional components of CMS 13. You should consider the timelines needed for each component in your go-live planning.
Use GitHub Copilot for AI-assisted modernization
The GitHub Copilot app modernization chat agent provides the following advantages during CMS upgrades:
- Accelerated development – Automates repetitive coding tasks and suggests solutions for common migration challenges.
- Reduced error rates – Helps identify potential issues and provides correct syntax or API usage.
- Knowledge transfer – Acts as an intelligent assistant, providing context-aware suggestions for new frameworks and libraries.
- Efficiency – Speeds up the overall migration timeline, allowing teams to focus on higher-value tasks.
For instructions on using GitHub Copilot, see the Microsoft and GitHub documentation. Test thoroughly after migration to verify the stability and functionality of your solution.
Upgrade to CMS 13
CMS 13 builds on the CMS 12 .NET foundation but introduces changes to service registration, API surfaces, and the site management model.
Prerequisites
- Existing CMS 12 solution – Your application should already be running on Optimizely CMS 12.
- .NET 10 SDK – CMS 13 requires .NET 10. Packages will fail dotnet restore on earlier .NET versions.
- Database backup – Create a full backup of your CMS database before starting.
- IDE – Visual Studio 2026 (18.0+) or a compatible IDE with .NET 10 support.
Pre-upgrade: Audit and prepare
Before changing any packages or code, audit your solution for potential compatibility issues.
❗️ Warning Search & Navigation (EpiServer.Find) is not supported in CMS 13. Refer to Migrate from Search & Navigation to Optimizely GraphMigrate from Search & Navigation to Optimizely Graph to replace the legacy content indexing, preview, and delivery pipeline. Implement search with Optimizely Graph or use your own search provider.
- Inventory third-party packages – Check each non-Optimizely NuGet package for a CMS 13-compatible version. Remove or disable incompatible packages before upgrading Optimizely packages. See Optimizely and third-party packages breaking changes for a list of commonly used packages and their compatibility.
- Document customizations – Note any custom scheduled jobs, custom content types, initialization modules, and integration points that may need updates.
- Resolve all obsolete warnings – CMS 13 removes APIs marked as [Obsolete] in CMS 12. Before upgrading, resolve all obsolete warnings in your CMS 12 build. Enable <TreatWarningsAsErrors>true</TreatWarningsAsErrors> in your .csproj file to catch these early. Any unresolved obsolete usage becomes a compilation error after upgrading.
- Review Optimizely Graph queries – The Optimizely Graph schema in CMS 13 contains breaking changes compared to CMS 12. Frontend applications that query Graph will require updates to reflect the new schema. Review your Graph queries and update them before going live.
- Review Conventions API changes – If you use the Conventions API to customize content indexing (computed fields, type exclusions, or indexing types), review the Conventions API migration guide for feature-by-feature migration instructions.
⚠️ Important Migrating DAM from CMS 12 If you use DAM with CMS 12, do not migrate your assets until migration tools are available. Other aspects of the CMS 12 to 13 upgrade can proceed in the meantime. The migration tools are prioritized and are planned for a release after CMS 13.0.0.
Third-party package compatibility Third-party package incompatibility is the single largest area of effort during a CMS 13 upgrade. Packages such as Geta.NotFoundHandler.Optimizely, Geta.Optimizely.Sitemaps, Geta.Optimizely.GenericLinks, Geta.Optimizely.ContentTypeIcons, and Advanced.CMS.AdvancedReviews may not yet have CMS 13-compatible versions. Removing these packages can cause cascading effects, including lost transitive dependencies and orphaned content types in the database. Plan for this work before you begin.
Removed features Dynamic Properties, Mirroring, and the legacy Plugin system were deprecated in CMS 12 and are fully removed in CMS 13. All related classes, interfaces, stored procedures, and database tables have been removed, including export/import APIs tied to these features. Search your codebase for references to the EPiServer.Core.DynamicProperty*, EPiServer.PlugIn, and mirroring-related transfer types, and remove or replace them before upgrading. See Breaking changes in CMS 13 for details.
Update target framework
Update your .csproj file to target .NET 10:
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
</PropertyGroup>If you use Docker, update your base images to .NET 10.
🚧 Important After changing the target framework to net10.0, your solution does not compile until you update the NuGet packages in the next step. This is expected. Do not attempt to build at this point.
Update NuGet packages
Update all EPiServer.* and Optimizely.* packages to their CMS 13 versions:
<PackageReference Include="EPiServer.CMS.UI.AspNetIdentity" Version="13.0.0" />
<PackageReference Include="EPiServer.Cms.UI.VisitorGroups" Version="13.0.0" />After updating, run dotnet restore to verify all packages resolve correctly.
dotnet restoreA successful restore completes with no errors:
Restore completed in 2.3s for MyProject.csproj.Common issues at this stage
Error | Cause | Resolution |
|---|---|---|
NU1202: Package X is not compatible with net10.0 | Third-party package does not support .NET 10 | Remove the package or find a CMS 13-compatible version. See Optimizely and third-party package breaking changes. |
NU1608: Detected package version outside of dependency constraint | Version conflict between Optimizely packages | Ensure all EPiServer.* and Optimizely.* packages target the same CMS 13 version (for example, 13.0.0). |
Missing type errors after removing packages | Lost transitive dependencies | Explicitly add the missing package (for example, Newtonsoft.Json). |
If dotnet restore succeeds but dotnet build produces errors, proceed to the Fix API breaking changes section. Compilation errors from API changes are expected at this stage and are addressed there.
📘 Note Removing packages like EPiServer.Find can cause you to lose transitive dependencies your code relies on, such as Newtonsoft.Json. If you encounter missing type errors after package cleanup, explicitly add the required package or migrate to System.Text.Json.
Update service registration
The service registration methods require the EPiServer.DependencyInjection namespace (not Microsoft.Extensions.DependencyInjection).
If your CMS 12 solution already uses AddCms(), this call continues to work in CMS 13 and is the recommended approach:
services.AddCms();Internally, AddCms() registers the following services:
services
.AddCmsHost()
.AddCmsCore()
.AddCmsHtmlHelpers()
.AddCmsTagHelpers()
.AddCmsUI()
.AddAdmin()
.AddTinyMce()
.AddCmsImageSharpImageLibrary()
.AddOptimizelyCmsServicev1()
.AddOAuthEndpoints()Granular service registration
If your CMS 12 solution uses granular service registrations instead of AddCms(), review the list above and add any registrations your solution is missing.
The following packages have been removed as core dependencies from EPiServer.CMS in CMS 13. If your solution uses them, ensure they are explicitly referenced in your .csproj file and their services are registered:
- EPiServer.CMS.UI.AspNetIdentity – Register with AddCmsAspNetIdentity<ApplicationUser>().
- EPiServer.Cms.UI.VisitorGroups – Register with both AddVisitorGroupsMvc() and AddVisitorGroupsUI().
The following example shows a complete CMS 13 service registration including optional packages:
services
.AddCmsAspNetIdentity<ApplicationUser>()
.AddCms()
.AddVisitorGroupsMvc()
.AddVisitorGroupsUI();⚠️ Important CMS 13 uses assembly scanning to discover referenced packages at startup. Every NuGet package your project references must either have its services explicitly registered (for example, AddTinyMce() for the TinyMCE editor) or be completely removed from your project. If a package is referenced but not registered, the application will fail at startup.
CMS 13 requires the SQL Server database compatibility level to be 140 or higher. If you have an older on-premises database, enable automatic compatibility level updates in your Startup.cs:
services.Configure<DataAccessOptions>(options =>
{
options.UpdateDatabaseCompatibilityLevel = true;
});Verify service registration
After updating service registrations, run dotnet build to verify the configuration compiles. The build may produce errors from API breaking changes (addressed in the following sections), but service registration issues produce distinct errors:
- 'IServiceCollection' does not contain a definition for 'AddCmsCore' – Add using EPiServer.DependencyInjection; (not Microsoft.Extensions.DependencyInjection).
- Startup crash: No service for type 'X' has been registered – A referenced package is missing its Add*() registration. Identify the package from the type name and add the corresponding registration, or remove the package entirely.
- Startup crash: Unable to find a module by assembly 'X' – A removed package still has references in your project. Search for and remove all using statements and service registrations that reference it.
Enable Content Manager and Optimizely Graph
🚧 Important If you are already using Optimizely Graph with CMS 12, before enabling Content Manager, complete the following:
- Enable GraphEnable Graphfor your project.
- Review the Graph schema comparison between CMS 12 and CMS 13.
- Update your code to the CMS 13 schema.
Content Manager and Optimizely Graph are not enabled by default in CMS 13 and require explicit opt-in. Graph is mandatory to use the full capabilities of CMS 13 (see Overview of CMS 13). The following CMS 13 features depend on Graph infrastructure:
- Optimizely OpalOptimizely Opal – Graph enables Optimizely Opal to index, interpret, and act on your content.
- Content Manager – The editorial experience relies on Graph for content discoverability.
- External content – Requires Graph indexing capabilities to connect external sources like DAM systems, PIMs, or other third-party applications, set up mappings, and manage content types to enable seamless access to external content.
- Content binding – Uses Graph structured queries to connect content items to external data sources or other content items. It enables automatic synchronization and structured relationships between content items.
📘 Note Before adding the Graph NuGet package, you must enable the Graph serviceenable the Graph service within the PaaS portal.
To add the NuGet packages, add the following to your .csproj file:
<PackageReference Include="Optimizely.Graph.Cms" Version="13.0.0" />
<PackageReference Include="EPiServer.Cms.UI.ContentManager" Version="13.0.0" />Or run the following commands:
dotnet add package Optimizely.Graph.Cms
dotnet add package EPiServer.Cms.UI.ContentManagerTo register the services, add the following to your Startup.cs :
services.AddContentGraph();
services.AddContentManager();❗️ Warning Register AddContentGraph() before AddContentManager() because Content Manager depends on Graph infrastructure. Reversing the order causes startup failures.
Adopt Graph at the beginning of your project. Adding Graph to an existing CMS 13 solution requires more effort than including it during initial setup.
See Get Started with Optimizely Graph for CMS 13 to configure Graph.
Fix API breaking changes
After updating packages, run dotnet build to surface compilation errors from API changes. Address these errors in any order because they are independent of each other. Continue fixing errors and rebuilding until dotnet build completes with zero errors.
The most common changes are listed below. For a complete list, see the CMS 13 breaking changes documentation and the API replacement map for a quick-reference lookup table.
SiteDefinition replaced by Application model
ISiteDefinitionResolver is replaced by IApplicationResolver in the EPiServer.Applications namespace. For code that used SiteDefinition.Current.RootPage, use ContentReference.RootPage instead.
// Before (CMS 12)
using EPiServer.Web;
public class MyController: Controller {
private readonly ISiteDefinitionResolver _siteResolver;
public MyController(ISiteDefinitionResolver siteResolver) {
_siteResolver = siteResolver;
}
}
// After (CMS 13)
using EPiServer.Applications;
public class MyController: Controller {
private readonly IApplicationResolver _applicationResolver;
public MyController(IApplicationResolver applicationResolver) {
_applicationResolver = applicationResolver;
}
}Start page resolution simplified
Replace IApplicationResolver.GetByContext() calls that retrieve the start page with ContentReference.StartPage:
// Before (CMS 12 / early CMS 13 previews)
var website = _applicationResolver.GetByContext() as Website;
var startPageContentLink = website?.RoutingEntryPoint;
// After (CMS 13)
var startPageContentLink = ContentReference.StartPage;The IRoutableApplication.EntryPoint property remains available for advanced scenarios that require explicit application context.
PageReference replaced by ContentReference
Replace all uses of PageReference with ContentReference and .PageLink with .ContentLink:
// Before (CMS 12)
PageReference pageRef = currentPage.PageLink;
// After (CMS 13)
ContentReference contentRef = currentPage.ContentLink;ContentArea.FilteredItems removed
ContentArea.FilteredItems is removed. Use ContentArea.Items instead:
// Before (CMS 12)
var items = myContentArea.FilteredItems;
// After (CMS 13)
var items = myContentArea.Items;📘 Note ContentArea.Items may have different filtering behavior than the previous FilteredItems property. Test content area rendering thoroughly after this change.
IContentTypeRepository no longer generic
Remove the generic type argument:
// Before (CMS 12)
IContentTypeRepository<ContentType> repo;
// After (CMS 13)
IContentTypeRepository repo;Service locator pattern replaced by dependency injection
Replace ServiceLocator and Locate.Advanced patterns with constructor injection:
// IInitializableModule before (CMS 12)
var loader = context.Locate.Advanced.GetInstance < IContentLoader > ();
// IInitializableModule after (CMS 13)
var loader = context.Services.GetRequiredService < IContentLoader > ();
// Service before (CMS 12)
public class MyClass {
public MyClass() {
var contentLoader = ServiceLocator.Current.GetInstance < IContentLoader > ();
}
}
// Service after (CMS 13)
public class MyClass {
private readonly IContentLoader _contentLoader;
public MyClass(IContentLoader contentLoader) {
_contentLoader = contentLoader;
}
}Additional breaking changes
Fix these to avoid compilation errors.
CMS 12 | CMS 13 | Notes |
|---|---|---|
InitializationEngine.Assemblies | AppDomain.CurrentDomain.GetAssemblies() | Assembly discovery changed |
Platform navigation HtmlHelpers | TagHelpers (for example, <epi-navigation-primary>) | UI helper migration |
Deprecation warnings
The following APIs are deprecated in CMS 13 and produce [Obsolete] compiler warnings. They continue to work in CMS 13 but are planned for removal in a future major version. Track these for future cleanup.
CMS 12/13 API | Status | Action |
|---|---|---|
PropertyDefinitionTypePlugInAttribute | Deprecated (planned removal in CMS 14) | Suppress warning for now; plan replacement before CMS 14 |
IPageRouteHelper | Deprecated (planned removal in CMS 14) | Suppress warning for now; plan replacement before CMS 14 |
Check for build errors
Run dotnet build. When the build completes with zero errors, you have resolved all blocking API breaking changes. Remaining [Obsolete] warnings are non-blocking and can be addressed after the upgrade is stable.
📘 Note If you still have errors, check the API replacement map for the specific type or method name. For errors not covered in this guide or the replacement map, consult the detailed breaking changes by topic articles.
Update admin URL references
The CMS admin path has changed from /EPiServer. The new path depends on your authentication setup:
- DXP-hosted with Opti ID – The default path is /ui/CMS.
- Self-hosted (without Opti ID) – The default path is /Optimizely/CMS.
Update any bookmarks, internal documentation, health checks, or hardcoded URL references in your codebase.
Configure the application model
CMS 13 replaces the sites concept with applications. The database migration automatically converts your existing site configuration into an In process application. After building and running your upgraded site for the first time, go to Settings > Applications in the CMS Admin interface and verify the migrated Application settings, including the start page and hostname.
Two application types are available:
- In process – The default application type assigned to migrated sites to support backwards compatibility.
- Headless – Provides stronger support for headless CMS scenarios with these key characteristics:
- Renders actual content in a separate application (such as Next.js, React, or Vue).
- Delivers CMS content using Optimizely Graph.
- Supports preview tokens for secure preview functionality.
See Application framework for more details.
Switch to the Headless application type
To switch your migrated application type from In process to Headless, complete the following steps:
- Go to Settings > Applications in the CMS admin interface.
- Delete the default In process application that the database migration creates.
- Create a Headless application.
- Set your start page as the application entry point.
- In the Hosts section, add your hostname as the default host.
Database and data considerations
The CMS 13 database migration runs automatically on first startup, but the following issues can occur:
- Schema migration failures – The schema migration may fail with SQL Error 1913 due to conflicting indexes. If this happens, manually drop the conflicting indexes identified in the error message, then restart the application to let the migration continue.
- Tab name validation – CMS 13 enforces alphanumeric-only identifiers for tab names (no spaces or special characters). If your content types use tab names like SEO Settings, change the identifier to an alphanumeric value and use the [Display(Name = "SEO Settings")] attribute for the display label.
Test and stabilize
After the code migration, complete the following verification steps:
- Resolve all compilation errors and review compiler warnings, which indicate further changes may be needed.
- Start the application and check the console output for startup exceptions or runtime errors.
- Confirm the CMS admin interface loads at /ui/CMS (or /Optimizely/CMS if self-hosting without Opti ID).
- Create, edit, preview, and publish content to verify the editorial experience works end to end.
- Verify pages render correctly, including content areas, blocks, and media.
- Check for [Obsolete] deprecation warnings in the build output. These are non-blocking but should be tracked for future cleanup before CMS 14.
Troubleshooting
- "No policy found" errors in the admin UI – A removed package was registering authorization policies that menu items depend on. Ensure the package is fully removed and no references to it remain.
- "Unable to find a module by assembly" errors – A removed package registered menu providers that are still referenced. Ensure the package is fully removed and no references to it remain.
Rollback and recovery
If the upgrade fails, the recovery procedure depends on whether the failure occurs before, during, or after first startup. First startup is the first time the CMS 13 application launches against the database, when the migration runs automatically.
The following sections cover three failure scenarios: before first startup, during or after first startup, and a partial database migration.
❗️ Warning The CMS 13 database migration is not reversible. When the migration runs on first startup, it permanently updates the database schema to CMS 13 format. A CMS 12 application cannot run against a CMS 13 database. Your pre-upgrade database backup (which you created in Prerequisites) is your only rollback path.
Failure before first startup
If the upgrade fails before first startup (code or package changes only), complete the following steps:
- Revert your code changes using source control.
- Run dotnet restore to restore CMS 12 package versions.
- Build the application.
- Run the application and confirm it works against the original database.
Failure during or after first startup
If the upgrade fails during or after first startup (database has migrated), complete the following steps:
- Stop the application.
- Restore the database from the backup created in Prerequisites.
- Revert your code changes using source control.
- Run dotnet restore.
- Run dotnet build to confirm the CMS 12 application compiles.
- Start the application.
- Verify it runs correctly against the restored database.
- Check application logs and the migration error output to diagnose the failure before attempting the upgrade again.
Partial database migration
❗️ Warning Do not attempt to re-run the migration against a partially migrated database.
If the migration fails midway, it may leave the database in an intermediate state. Common causes include SQL Error 1913 and timeouts.
Restore from backup, resolve the root cause, and retry the upgrade from a clean state. For guidance on root causes, see Database and data considerations.
Deploy on DXP
If your Optimizely CMS is hosted on DXP, the deployment path depends on whether you are already using Optimizely Graph on CMS 12.
Already using Graph on CMS 12
Because there are schema-breaking changes to Optimizely Graph between CMS 12 and CMS 13, you need a dedicated migration process to create a new CMS 13 project alongside your existing CMS 12 project. This lets you validate the upgrade without impacting your live site.
See Migrate from CMS 12 to CMS 13 with Optimizely Graph for detailed steps.
Not yet using Graph on CMS 12
If you have not yet implemented Graph on CMS 12, your migration path follows the standard upgrade process in the PaaS Portal. Graph provisioning is added as an extra step in your existing CMS project. Deploy to Integration, then Preproduction, and then Production. In this case, there is no CMS 12 production instance running in parallel with a CMS 13 production instance.