Optimizely CMS 12 to CMS 13 upgrade guide: path, effort and timing

Optimizely released CMS 13 on March 31, 2026, built on .NET 10. With .NET 8 support ending on November 10, 2026, many CMS 12 teams assume they must upgrade before that date. They do not, but they do need a plan. This guide separates the urgent framework decision from the larger CMS 13 project, lists what breaks, and lays out an upgrade path with the drivers of effort.

What CMS 13 changes

According to the CMS 13 general availability release notes, CMS 13 is a major release that moves the platform to .NET 10 and builds the content management experience around headless delivery, visual authoring and Optimizely Graph. Graph and Opti ID become mandatory components, included in the CMS 13 license.

For editors, the visible changes are Content Manager, a search-first interface for finding content that runs on Optimizely Graph, and Visual Builder, which replaces on-page editing. On-page editing is turned off by default in CMS 13 and can be enabled in configuration.

GEO and AI visibility features

CMS 13 also brings tools for generative engine optimization (GEO). The CMS 13 release notes describe two that matter for most marketing teams:

• GEO Schema Optimization agent: analyzes page content and recommends or generates schema types and JSON-LD markup, so content is easier for search engines and large language models to read.
• Agent Visibility Analytics dashboard: released June 10, 2026 in Optimizely Analytics. It uses content delivery network (CDN) log data and Agent Platform insights to show AI traffic patterns, which AI platforms visit most often, and which pages attract the most AI attention.

Optimizely's why upgrade page adds GEO metadata and question-and-answer fields, a GEO Recommendations agent that checks pages against GEO practices, and GEO Analytics that tracks how AI crawlers access your content.

Do you have to upgrade before November 10, 2026?

No. Microsoft ends support for .NET 8 and .NET 9 on November 10, 2026. In May 2026, Optimizely confirmed that CMS 12 is fully compatible with .NET 10, and that it tested CMS 12 with add-ons such as Optimizely Forms and Language Manager on .NET 10. The fastest way to stay on a supported framework is to move your CMS 12 solution to .NET 10.

One exception: at the time of that post, Optimizely Commerce 14 did not yet support .NET 10, and Optimizely expected a compatible release in late Q2 or early Q3 2026. If you run Commerce, check the current status before you plan the framework move.

This splits the work into two decisions. The framework move is urgent and relatively small. The CMS 13 upgrade is larger and can follow a schedule that suits your business. Staying on CMS 12 for now is a legitimate choice.

What breaks between CMS 12 and CMS 13

The CMS 13 upgrade guide and the breaking changes list are the references. The changes most likely to affect your project:

• Search & Navigation (Find) is gone. CMS 13 does not support Optimizely Search & Navigation. You implement search with Optimizely Graph or a third-party search provider. Optimizely ships a Graph C# SDK with a query style similar to Search & Navigation to ease the move.
• Graph schema changes. The Graph schema in CMS 13 breaks compatibility with CMS 12, so a CMS 12 site and a CMS 13 site cannot share one Graph instance. Front ends that query Graph need updated queries. On DXP, the Prepare for CMS 13 option provisions a separate Graph instance so you can upgrade without Graph downtime.
• Removed features. Dynamic Properties, Mirroring and the legacy Plugin system are fully removed.
• Sites become applications. The SiteDefinition model moves to Applications, with routing and URL changes.
• Framework changes. Newtonsoft moves to System.Text.Json, Castle.Windsor is removed, the service locator pattern gives way to dependency injection, and PageReference is replaced by ContentReference.
• Removed obsolete APIs. Many methods marked obsolete in earlier versions are deleted. Fix compiler warnings before you start.
• Add-on compatibility. Optimizely documents known incompatibilities with Find, Forms, Geta packages and other extensions. Optimizely Forms 6.0.0, released April 9, 2026, targets CMS 13.

Upgrade path, step by step

1. Move CMS 12 to .NET 10 on the latest CMS 12 packages, and clear every obsolete-API warning.
2. Take inventory: Search & Navigation usage, Graph queries, add-ons, custom plugins, Dynamic Properties, multi-site setup and integrations.
3. Choose your search approach: Optimizely Graph, or a third-party provider such as Coveo if search is central to your site or intranet.
4. Set up the CMS 13 project alongside CMS 12. Optimizely recommends a dedicated migration process with a new CMS 13 project next to the existing one, so you validate without touching the live site.
5. Upgrade the code: packages, dependency injection, serialization, sites to applications and removed APIs.
6. Rebuild search and update front-end Graph queries against the new schema.
7. Prepare editors for Content Manager and Visual Builder, and decide whether to re-enable on-page editing.
8. Test and cut over: content, French and English routing, redirects, forms and performance, then switch traffic.

Effort drivers

Driver	Lower effort when	Higher effort when
Search & Navigation	Not used, or used for a few simple listings	Search, facets and listings across the site depend on it
Optimizely Graph	Not used yet, or used by one front end	Several headless front ends query Graph
Code health	Few obsolete-API warnings, dependency injection already used	Service locator, Newtonsoft and removed APIs throughout
Add-ons	Only Optimizely add-ons with CMS 13 versions	Third-party packages without CMS 13 versions
Site structure	One site, one or two languages	Many sites on one instance with complex routing
Commerce	CMS only	Commerce 14 in the same solution
Editors	Small team, simple page types	Large team that relies on on-page editing

When to upgrade

Before November 10, 2026, move CMS 12 to .NET 10. After that, schedule CMS 13 when one of these applies: you need to replace Search & Navigation anyway, you want the GEO tools and Agent Visibility Analytics, you are planning a headless front end on Graph, or you are starting a redesign that would otherwise be built twice. This guide does not assume a CMS 12 end-of-support date. Confirm the date that applies to your contract with Optimizely.

How a platform assessment helps

Sengo is a bilingual EN/FR team in Canada that works across Optimizely, Sitecore, Kentico, Umbraco, Contentful, Storyblok and Coveo. Our free Optimizely assessment reviews your CMS 12 solution, flags Search & Navigation and Graph dependencies, and gives you an upgrade plan with the effort drivers listed, including whether staying on CMS 12 for now is the smarter move.