Understanding Removals

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

Average rating: 0 No reviews

Outline

At a glance

Architectural shift: SiteDefinitions retire in favor of a unified Application-centric model
API cleanup: Legacy types like PageReference and generic content repositories are fully decommissioned
Service resolution: Static location patterns are out; standard IServiceProvider injection is the required path
Identity mandate: Administrative security moves from local tables to centralized Opti ID management

The transition to Optimizely CMS 13 includes a deliberate cleanup of the core framework. Several architectural fixtures that have persisted since the early days of CMS 11 and 12 are being decommissioned or replaced with more flexible, platform-ready alternatives. These removals are necessary to support the multi-product interoperability of the Optimizely One ecosystem and to fully leverage the .NET 10 runtime.

1. The Shift from SiteDefinitions to the Application Model

One of the most consequential material changes in CMS 13 is the replacement of the SiteDefinition model. Historically, a "Site" was the primary unit of configuration, tying a content root to a hostname. CMS 13 introduces an Application-centric model that distinguishes between rendering modes and connection types.

Architectural Impact

Administrative configuration has moved from the legacy site settings tab to a new modular interface under Settings → Applications.

Application Types: Definitions are now split into "In-Process" (standard ASP.NET Core applications) and "Headless" (remote applications consuming content via APIs).
Repository Retirement: The ISiteDefinitionRepository is officially deprecated. Technical teams must transition to the IApplicationRepository to manage both local and remote application contexts.
Resolution Logic: Dependency on SiteDefinition.Current is no longer supported. The IApplicationResolver must be injected to determine the current application context asynchronously.

// Replacement pattern for resolving application context
public class ApplicationService
{
    private readonly IApplicationResolver _applicationResolver;

    public ApplicationService(IApplicationResolver applicationResolver)
    {
        _applicationResolver = applicationResolver;
    }

    public async Task<Guid> GetCurrentApplicationIdAsync()
    {
        var app = await _applicationResolver.GetByContextAsync();
        return app.Id;
    }
}

2. Core Framework API Removals

CMS 13 systematically removes APIs that were marked as obsolete in v12. This cleanup aims to unify content handling and enforce modern dependency injection (DI) standards.

Content Reference Unification

The legacy PageReference type is removed. All references must now utilize the base ContentReference type. This change reflects the removal of page-specific logic from core content loading APIs.

PageLink Retirement: Properties like PageData.PageLink are replaced by ContentLink.
Type Safety Cleanup: The generic overload of IContentTypeRepository<T> is removed. Repositories now utilize the non-generic IContentTypeRepository.

Service Location Decommissioning

The use of InitializationEngine.Locate or context.Locate for service resolution within initialization modules is no longer supported. The framework now enforces the use of IServiceProvider.

// Required Pattern (CMS 13)
public void Initialize(InitializationEngineContext context)
{
    var loader = context.Locals.GetRequiredService<IContentLoader>();
}

3. UI Shell and Tag Helper Evolution

The administrative shell UI has undergone significant refactoring to align with the centralized Optimizely navigation system.

Navigation Tag Helpers: Legacy shell navigation components are removed. Developers must replace custom shell extensions with the new <platform-navigation /> tag helper.
On-Page Edit (OPE) Removal: The legacy "On-Page Edit" view is disabled by default in CMS 13. The modernized Visual Builder serves as the primary gateway for in-context editing.

4. Security and Role Management Removals

With the mandate of Opti ID, the way technical users are authorized within the administrative boundary has materially changed.

Virtual Role Mappings: Legacy virtual role configurations within artifacts like appsettings.json are retired for administrative users. These mappings are now handled via user-to-group assignments within the Opti ID Admin Center.
Local Identity Tables: Dependencies on local AspNetIdentity tables for administrative access are removed. Technical access to the shell (/episerver) is now strictly tied to the Opti ID authentication scheme.

Conclusion

The removal of legacy admin tooling and obsolete APIs in CMS 13 is a strategic reduction of framework "bloat." By decommissioning older site-centric definitions and proprietary service location patterns, Optimizely provides a cleaner integration point for modern .NET 10 development. Successfully navigating these removals requires a proactive approach to code auditing, specifically around SiteDefinition usage, PageReference types, and custom UI extensions. This cleanup ensures that the final upgraded solution is not only performant but also fully compatible with the broader Optimizely One platform architecture.