Key Platform Changes

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

Average rating: 0 No reviews

Outline

At a glance

Biggest shift: CMS 13 moves to .NET 10 and introduces application-based site management
Code impact: Project files, startup registration, site resolution, and shell UI patterns all change
PaaS reality: Opti ID, Graph, and explicit service registration become more important
Migration mindset: This is evolutionary, but not “change nothing and pray” territory

Introduction

Migrating from Optimizely CMS 12 to CMS 13 is designed to be an evolution rather than a complete re-architecture. However, developers still need to navigate several platform-level shifts that affect everything from project file structure to how site settings are resolved in code.

In this page, we break down the fundamental changes you must address when moving PaaS solutions to CMS 13.

1. The .NET 10 Framework Leap

The most immediate change is the requirement for .NET 10. While CMS 12 commonly ran on .NET 6 or .NET 8, CMS 13 moves the baseline to the latest long-term support generation in the platform’s roadmap.

1.1 The `.csproj` Update

Your project file must be updated to target the new framework. If this is not done, package compatibility issues will show up quickly during restore and build.

Before (CMS 12): <TargetFramework>net8.0</TargetFramework>
After (CMS 13): <TargetFramework>net10.0</TargetFramework>

If your solution uses a global.json file to pin the SDK version in CI/CD, that file should also be updated to a compatible 10.x SDK.

2. Reimagining the “Site”: The Application Model

For many years, developers used Site Definitions to map hostnames to root content. In CMS 13, that model is deprecated in favor of Applications.

2.1 Why the Change?

The new model supports a more composable and multi-head architecture. In older versions, a site was assumed to be an in-process web application. In CMS 13, an application can represent multiple delivery styles.

Website: The traditional in-process CMS delivery head.
Remote Website: A headless or remote delivery head, such as Next.js, that consumes CMS content but is still managed inside the same administrative model.

2.2 Programmatic Changes

Developers must update code to use the new application-oriented resolution patterns.

CMS 12 vs. CMS 13 resolution patterns

Repository: ISiteDefinitionRepository becomes IApplicationRepository.
Current Context: SiteDefinition.Current gives way to IApplicationResolver.GetApplication().
Identifiers: GUID-based IDs are replaced with immutable application names.

Action item: After upgrading, the admin interface may return 404s until your previous site setup is reconfigured as applications inside the CMS admin settings.

3. Modernizing the Shell: Navigation and UI

If you have custom admin pages, dashboards, or add-ons, the way CMS renders top-level navigation has changed. Legacy HTML helpers are replaced by tag helpers.

3.1 Layout Updates

In shell layouts, you now include the EPiServer.Shell.UI tag helper:

@addTagHelper *, EPiServer.Shell.UI

You also replace the older navigation helper:

Old: @Html.CreatePlatformNavigationMenu()
New: <platform-navigation />

This aligns CMS 13 with the newer unified platform navigation used across Optimizely’s SaaS and PaaS products.

4. Under the Hood: Startup and Database Shifts

CMS 13 simplifies some configurations while making others more explicit. That means fewer assumptions and more deliberate registration in startup code.

4.1 Mandatory Service Registration: `AddVisitorGroups()`

In CMS 12, visitor groups could feel implicitly available depending on project setup. In CMS 13, if your application uses personalization, you should explicitly register visitor groups in ConfigureServices.

4.2 Database Compatibility Auto-Updates

In PaaS and DXP pipelines, schema compatibility matters a lot. CMS 13 recommends enabling automatic compatibility updates:

services.Configure<DataAccessOptions>(options => 
{
    // Allows the schema to be updated automatically to version 13.x compatibility
    options.UpdateDatabaseCompatibilityLevel = true;
});

4.3 Static Web Assets (Blazor Support)

For teams building UI extensions with Blazor or Razor Class Libraries, .NET 10 can introduce stricter expectations around static web assets. In some cases, you may need this in your project file:

<PropertyGroup>
    <RequiresAspNetWebAssets>true</RequiresAspNetWebAssets>
</PropertyGroup>

5. From DXP Identity to Opti ID

In the PaaS context, CMS 13 moves away from relying on local AspNetIdentity storage for editorial and administrative users. Opti ID becomes the primary SSO gateway.

5.1 What Should Developers Change?

Login Logic: If you used custom editor login flows, you should transition toward the standardized Opti ID model.
Service Registration: Use services.AddOptimizelyIdentity() in startup configuration.
Role Management: Roles for editors and administrators are increasingly managed in the Opti ID Admin Center instead of relying heavily on local database roles.

6. Summary of Obsolete APIs

To get to a cleaner CMS 13 state, audit your codebase for several important removals and replacements:

PageReference → Use ContentReference.
EPiServer.Find → Move search strategy toward Optimizely Graph.
SiteDefinitionRepository → Use ApplicationRepository.

Conclusion

CMS 13 does not ask developers to throw away everything they learned in CMS 12, but it does require a real platform mindset update. The move to .NET 10, the application model, modern shell navigation, explicit visitor group registration, and Opti ID all push the platform toward a more composable and standardized future. In other words, same Optimizely family, but the furniture has definitely been rearranged.