Breaking changes in CMS 13
When you upgrade to Content Management System (CMS 13), breaking changes may disrupt or alter your existing code, integrations, or customizations. Handling breaking changes ensures a smooth transition and continued CMS operation.
Follow these steps:
- Review breaking changes – Carefully read the breaking changes in this document and the detailed articles in the following list.
- Assess impact – Identify which parts of your current implementation are affected by the breaking changes. Review custom code, third-party integrations, and extensions that rely on deprecated or altered features.
- Plan for changes – Develop a plan to refactor or update the affected areas of your codebase. This might include rewriting custom code, updating APIs, or replacing deprecated features with their replacements.
- Test in a staging environment – Configure a staging environment to test the upgrade process before applying it to the production environment. This helps you identify and fix issues without affecting live operations.
- Refactor code and update integrations – Make necessary changes to your code and integrations based on the assessment and testing. Ensure that dependent systems and workflows continue to function correctly.
- Update documentation – Revise any internal documentation that references the old system behavior. This helps ensure that your team is aware of the new processes and any changes to functionality.
- Conduct user training – If the breaking changes affect end-user functionality or workflows, provide training or resources to help users adjust to the new system.
- Perform regression testing – Conduct thorough regression testing to ensure that the changes have not introduced new bugs or issues in existing functionalities.
- Monitor post-upgrade – After upgrading, closely monitor the system for any unexpected behavior or issues and be prepared to address them promptly.
Following these steps helps you manage breaking changes and upgrade with minimal disruption.
Manage CMS 13 breaking changes
CMS 13 breaking changes to method signatures or to the behavior of methods, compared to the documented API in CMS 12, are described across the following articles. Each article groups related changes by area of concern.
📘 Note Binary breaking changes do not necessarily require code changes but rather just a recompilation of the project.
A breaking change may cause a component to fail. When a breaking change is made to a signature of a method, class, or interface, the former signature is often kept intact but set as obsolete and may cause a warning message in Visual Studio. To delay fixing the warning messages, you can disable Treat Warnings as Errors by right-clicking on your project > Properties > Build and set Treat Warnings as Errors to Specific warnings or None.
Classes with dependency-accepting constructors are removed without an obsolete warning in major releases. The compiler indicates the required changes. Keeping those classes makes dependency injection complex because, over time, there would be multiple constructors to choose from that might overlap.
In each major version, obsolete methods are removed permanently to keep the API clean and usable. If you postpone fixing warning messages, ensure you fix them before upgrading to a major version. In CMS 13, many methods made obsolete in prior versions are removed.
Breaking changes by topic
- Framework and platform changes – .NET 10 requirement, NuGet restructuring, dependency injection namespace changes, serialization removals, Newtonsoft to System.Text.Json migration, Castle.Windsor removal, and nullable annotation updates.
- Content types and property definitions – Content type, property definition, and tab definition name validation. Dynamic Properties removal. Block type changes. Content type repository behavior changes.
- Content management and repository – IContentRepository, ContentProvider, ContentArea, XhtmlString, content versioning, validation system overhaul, and SaveAction changes.
- Sites-to-applications and routing – SiteDefinition to Application migration, UriSupport replacement, routing changes, and URL segment updates.
- Security and access control – PrincipalInfo, AccessControlEntry, AccessControlList, preview tokens, approval engine, and content security events.
- Scheduling, plugins, and events – Plugin system removal, scheduled job requirements, event system security changes, and caching updates.
- UI, editors, and shell – Platform navigation, editor descriptors, TinyMce, shell modules, menu system, DAM integration, and admin UI changes.
- Localization and import or export – LocalizationService and LocalizationProvider signature changes, import or export and transfer context updates, and mirroring removal.
- Optimizely and third-party package compatibility – Known incompatibilities with Optimizely Find, Optimizely Forms, Geta packages, and other third-party extensions. Workarounds and removal guidance.
- API replacement map – Quick-reference tables mapping CMS 12 types, methods, events, and namespaces to their CMS 13 replacements, including extracted packages and removed APIs.