Optimizely CMS, DXP, AI editor tools, and technical SEO

Optimizely ships a C# SDK for building custom tools that plug directly into Opal (now rebranded as Agent Platform, personified as Mark). If you already build on .NET for Optimizely CMS, this is the fastest way to expose your own logic, your own packages, or your own data to a conversational interface without writing a separate service in Python or Node.

A quick naming note before the code: as of September 1, 2026, Optimizely is rebranding Opal to Agent Platform, with the assistant personified as Mark. The product documentation has already moved to the new names, but the SDK surface still uses Opal terminology: the NuGet package, the OpalTool attributes, and the AddOpalToolService and MapOpalTools methods. This post uses "Opal" for anything code-related and for the registry steps, because that is what the SDK calls it. Menu names in your instance may differ slightly depending on when it was updated.

This post was written against Optimizely.Opal.Tools version 0.7.8. The package is still pre-1.0, so APIs may change between releases.

There is also a package naming trap worth calling out early: OptimizelyOpal.OpalToolsSDK is the old package and is now unlisted on NuGet. The current, actively maintained package is Optimizely.Opal.Tools. Some older documentation pages still link to the old name, so if you land on it, your tutorial will not match what ships today.

Install the SDK

dotnet add package Optimizely.Opal.Tools

This targets .NET 8.0 or later. If your CMS project already runs on .NET 8 or later, it can be added directly. Projects on an older runtime need to be upgraded first.

Register the Tool Service

In your existing Program.cs (the one that already contains your CMS setup), add the Opal tools service and register each tool class individually:

using Optimizely.Opal.Tools;

var builder = WebApplication.CreateBuilder(args);

// ... your existing CMS registrations ...

// Add the Opal Tools service
builder.Services.AddOpalToolService();

// Register each tool class
builder.Services.AddOpalTool<ContentStatusTool>();

var app = builder.Build();

// Protect the tool endpoints (see "Secure the Endpoints" below)
app.UseMiddleware<OpalBearerTokenMiddleware>();

// Map the discovery and execution endpoints
app.MapOpalTools();

app.Run();

app.MapOpalTools() wires up everything Opal needs to find and call your tool:

• GET /discovery, listing every registered tool and its parameter schema
• POST /tools/{tool-name}, the execution endpoint Opal calls when a user triggers the tool
• POST /tools/callbacks/{ToolClassName}/{method-name}, used for interactive tool callbacks
• POST /interactions/execute, used for app-only interactions if you declare any with [OpalInteraction]

You can pass a prefix to MapOpalTools("opal") if you want to namespace these routes alongside existing CMS or API endpoints. Note that this changes the URLs: with that prefix the discovery endpoint becomes /opal/tools/discovery, so use that URL when you register the tool.

Secure the Endpoints

This step is easy to miss and it matters. Registering a tool means exposing /discovery and the execution endpoints on a public HTTPS URL. The token you enter in the registry only tells Opal what to send in the Authorization header. Nothing validates it on your side unless you add that check. Without it, anyone who finds the URL can call your tools.

Here is a small middleware that rejects any request to the Opal routes unless it carries the expected bearer token. The token comes from configuration (user secrets locally, Azure Key Vault or an app setting in production), never from source code:

using System.Security.Cryptography;
using System.Text;

public class OpalBearerTokenMiddleware
{
    private static readonly string[] ProtectedPrefixes = { "/discovery", "/tools", "/interactions" };

    private readonly RequestDelegate _next;
    private readonly byte[] _expectedToken;

    public OpalBearerTokenMiddleware(RequestDelegate next, IConfiguration configuration)
    {
        _next = next;

        var token = configuration["Opal:BearerToken"];
        if (string.IsNullOrWhiteSpace(token) || token.Length < 32)
        {
            // Fail at startup rather than silently running unprotected
            throw new InvalidOperationException("Opal:BearerToken must be configured with at least 32 characters.");
        }

        _expectedToken = Encoding.UTF8.GetBytes(token);
    }

    public async Task InvokeAsync(HttpContext context)
    {
        if (ProtectedPrefixes.Any(p => context.Request.Path.StartsWithSegments(p)))
        {
            var header = context.Request.Headers.Authorization.ToString();
            const string scheme = "Bearer ";

            var provided = header.StartsWith(scheme, StringComparison.OrdinalIgnoreCase)
                ? Encoding.UTF8.GetBytes(header[scheme.Length..].Trim())
                : Array.Empty<byte>();

            // Constant-time comparison to avoid leaking the token through timing
            if (!CryptographicOperations.FixedTimeEquals(provided, _expectedToken))
            {
                context.Response.StatusCode = StatusCodes.Status401Unauthorized;
                return;
            }
        }

        await _next(context);
    }
}

If you used a prefix such as MapOpalTools("opal"), add that prefix to ProtectedPrefixes. Put the same token in the registry's Bearer Token field when you register the tool. Generate it with a cryptographically secure random generator and rotate it if it is ever exposed.

One more thing to know: Optimizely's documentation currently notes that Opti ID is the only provider supported for tool authentication, while the registry also has a bearer token field. Check the current "Create custom tools" page for the latest guidance, and move to Opti ID as soon as it suits your setup.

Build Your First Tool

A tool is just a class with a method decorated with [OpalTool]. Here is a practical example for anyone running Optimizely CMS: a tool that counts how many pages are currently sitting in draft under a given root, something editors ask about constantly and usually have to check manually in the CMS UI.

using EPiServer;
using EPiServer.Core;
using EPiServer.DataAbstraction;
using EPiServer.Web;
using Optimizely.Opal.Tools;
using System.ComponentModel;
using System.ComponentModel.DataAnnotations;

public class DraftPageCountParameters
{
    [Description("Content reference ID of the root page to scan, for example 5 or 5_123. Defaults to the site start page if omitted.")]
    [StringLength(20)]
    [RegularExpression(@"^\d+(_\d+)?$", ErrorMessage = "RootContentLink must look like 5 or 5_123.")]
    public string? RootContentLink { get; set; }
}

public class ContentStatusTool
{
    private readonly IContentLoader _contentLoader;
    private readonly IContentVersionRepository _versionRepository;

    public ContentStatusTool(IContentLoader contentLoader, IContentVersionRepository versionRepository)
    {
        _contentLoader = contentLoader;
        _versionRepository = versionRepository;
    }

    [OpalTool(Name = "count-draft-pages")]
    [Description("Counts how many pages currently have an unpublished draft version under a given root page in Optimizely CMS")]
    public object CountDraftPages(DraftPageCountParameters parameters)
    {
        // Parameters come from an LLM, so treat them as untrusted input
        ContentReference root = ContentReference.StartPage;
        if (!string.IsNullOrEmpty(parameters.RootContentLink)
            && !ContentReference.TryParse(parameters.RootContentLink, out root))
        {
            return new { error = "RootContentLink is not a valid content reference." };
        }

        if (!_contentLoader.TryGet<PageData>(root, out _))
        {
            return new { error = "The root page could not be found." };
        }

        var descendants = _contentLoader.GetDescendents(root);

        // IContentLoader returns the published version, so look up the latest
        // common draft for each page to find pages with unpublished changes.
        var draftCount = _contentLoader
            .GetItems(descendants, LanguageSelector.MasterLanguage())
            .OfType<PageData>()
            .Count(p => _versionRepository.LoadCommonDraft(p.ContentLink, p.LanguageBranch)?.Status == VersionStatus.CheckedOut);

        return new { draftCount, scannedRoot = root.ToString() };
    }
}

Register it alongside your other tools:

builder.Services.AddOpalTool<ContentStatusTool>();

That is the whole tool. No manual JSON schema, no separate discovery file to maintain. The [Description] attributes on the parameter class and the method tell Opal what the tool does and what it expects, and the SDK generates the schema for you from the C# types. The validation attributes keep the input to a strict allow-list format.

Three things to keep in mind with this example:

• It runs as the service, not as the Opal user. IContentLoader does not apply per-user access rights, so the tool can count pages the calling user may not be able to see. That is acceptable for a count of drafts on a site your whole editorial team works on. For anything that returns page names, URLs or content, filter results by the caller's access rights or limit the tool to specific roots.
• It is not cheap on large sites. Counting loads every descendant page. For a big tree, cache the result briefly or scope the root tightly.
• Test it against a real CMS instance. "Draft" depends on your content workflow (for example scheduled or awaiting approval pages), so check the status values match what your editors call a draft.

Dependency Injection Works As Expected

Tool classes are resolved through the standard ASP.NET Core container, so constructor injection works exactly as it does in a controller. The example above injects IContentLoader and IContentVersionRepository directly. If your tool needs configuration, a logger, or a service from one of your own NuGet packages, just add it to the constructor.

The following sketch uses a hypothetical IVisitorGroupUsageService and parameter class from your own package, to show the pattern:

public class VisitorGroupUsageParameters
{
    [Required]
    [StringLength(100)]
    [Description("Name of the Visitor Group to look up")]
    public string VisitorGroupName { get; set; } = string.Empty;
}

public class VisitorGroupUsageTool
{
    private readonly IVisitorGroupUsageService _usageService;
    private readonly ILogger<VisitorGroupUsageTool> _logger;

    public VisitorGroupUsageTool(IVisitorGroupUsageService usageService, ILogger<VisitorGroupUsageTool> logger)
    {
        _usageService = usageService;
        _logger = logger;
    }

    [OpalTool(Name = "visitor-group-usage")]
    [Description("Returns which pages and blocks reference a given Visitor Group")]
    public async Task<object> GetUsage(VisitorGroupUsageParameters parameters)
    {
        _logger.LogInformation("Checking usage for visitor group {GroupName}", parameters.VisitorGroupName);
        var usage = await _usageService.GetUsageAsync(parameters.VisitorGroupName);
        return new { parameters.VisitorGroupName, usage };
    }
}

This is the pattern worth noticing if you already maintain Optimizely add-ons: any existing service in your package can be wrapped in an Opal tool with a handful of lines, without touching the package's existing logic at all. Remember to register this class with AddOpalTool<VisitorGroupUsageTool>() too.

Authentication to Third-Party Providers

If a tool needs to call out to a third-party provider on behalf of the user, decorate it with [OpalAuthorization] and accept an OpalToolContext parameter. This is an illustrative sketch, and the calendar events returned here are placeholders:

[OpalTool(Name = "get-calendar")]
[Description("Gets the user's calendar events")]
[OpalAuthorization("google", "calendar")]
public object GetCalendar(CalendarParameters parameters, OpalToolContext context)
{
    var authData = context.AuthorizationData;
    var credentials = authData?.Credentials;

    // use credentials to call the provider's API
    // never log or return the credentials themselves
    return new { events = new[] { "Event 1", "Event 2" } };
}

This is separate from protecting your own endpoints. For tools that only talk to your own CMS instance, like the draft page counter above, you do not need [OpalAuthorization], but you do need the bearer token check from the previous section.

Register the Tool in Opal

1. Deploy your project so the discovery endpoint is reachable over HTTPS, and make sure the bearer token is set in the deployed environment's configuration.
2. In your Opal instance, go to Connectors > Registries.
3. Click Add tool registry and enter a registry name.
4. Enter your discovery endpoint URL in the Discovery URL field, for example https://yoursite.com/discovery (or https://yoursite.com/opal/tools/discovery if you used a prefix).
5. Enter the same token in the Bearer Token field. The field is labelled optional in the UI, but your endpoints should not be left open, so treat it as required.
6. Click Save.

Once saved, your tool appears under Tools > Tools, where you can toggle it active or inactive, and enable or disable it in chat.

Important

• Do not install OptimizelyOpal.OpalToolsSDK. It is unlisted and no longer maintained. Use Optimizely.Opal.Tools.
• Never leave the tool endpoints unauthenticated, and never commit the bearer token to source control.
• Treat every tool parameter as untrusted input. The model decides what to send, and it can be influenced by whatever content it has read. Validate in your own code rather than relying on the description text.
• Keep tool method names short and specific. The LLM selects which tool to call based on the name and description, so vague names like get-data lead to the wrong tool being picked in a busy registry.
• Avoid putting secrets or connection strings directly in a tool class. Use configuration and the standard ASP.NET Core options pattern, the same as you would for any other service.
• Tool names must be unique within a registry. If you are wrapping several packages, keep related tools together and name them clearly so they do not collide.

Links

• Optimizely.Opal.Tools on NuGet
• Create custom tools
• Add a custom tool to Agent Platform
• Agent Platform documentation

If you have worked on any Optimizely CMS 12 codebase, chances are you have written code like this in a controller, block component, or view model factory:

// CMS 12 pattern
if (currentPage.MainContentArea?.FilteredItems?.Any() == true)
{
    var visibleBlocks = currentPage.MainContentArea.FilteredItems
        .Select(item => _contentLoader.Get<IContent>(item.ContentLink))
        .ToList();
}

In Optimizely CMS 13, ContentArea.FilteredItems is marked [Obsolete] and scheduled for complete removal in CMS 14. If you enable <TreatWarningsAsErrors>true</TreatWarningsAsErrors> as recommended for your CMS 13 upgrade, any direct reference to FilteredItems will fail your build.

Here is why Optimizely made this change, when you actually need to fix it, and how to implement a clean, dependency-injection-friendly replacement in CMS 13.

Why ContentArea.FilteredItems Was Deprecated

ContentArea is supposed to be a pure content data model (a POCO). However, in CMS 12 and earlier versions, calling contentArea.FilteredItems forced the property getter to secretly call a static ServiceLocator behind the scenes to resolve permissions, publish status, and visitor group evaluators.

This hidden service locator dependency broke clean architecture principles, made unit testing difficult, and caused issues with asynchronous execution pipelines in modern ASP.NET Core.

In CMS 13, Optimizely separated data from evaluation: ContentArea holds only raw items (contentArea.Items), while filtering is handled explicitly by injected services.

When You Do (and Do Not) Need to Change Your Code

1. Standard Razor Views: No Change Needed

If you render content areas in your Razor views using tag helpers or the standard HTML helper:

<!-- No migration needed -->
<epi-property property-name="MainContentArea" />
@Html.PropertyFor(x => x.CurrentPage.MainContentArea)

The internal ContentAreaRenderer pipeline automatically applies all access checks and personalization filters during HTML generation, exactly as it did in CMS 12.

2. C# Backend Code: Migration Required

If you access FilteredItems directly in C# (such as checking whether a content area has visible blocks for the current user, calculating item counts, or mapping blocks to custom DTOs), you must migrate.

Warning: Never blindly replace contentArea.FilteredItems with contentArea.Items. The Items collection contains raw, unfiltered references, including expired blocks, unpublished drafts, and blocks restricted to specific Visitor Groups or roles. Doing so will leak restricted content to anonymous visitors.

The CMS 13 Replacement: IContentAreaItemsRenderingFilter

To evaluate item visibility in C#, CMS 13 provides the IContentAreaItemsRenderingFilter interface. Optimizely registers two built-in filter implementations out of the box:

• ContentAreaItemAccessFilter: Evaluates content access permissions and publishing status.
• VisitorGroupContentAreaItemsFilter: Evaluates visitor group criteria for the current request.

You can inject IEnumerable<IContentAreaItemsRenderingFilter> into any controller, service, or factory and run the filters against contentArea.Items.

Step-by-Step Implementation

Option 1: Injecting Filters Directly into a Controller or Service

using EPiServer.Core;
using EPiServer.Cms.Shell.UI.Rest.ContentAreas;
using Microsoft.AspNetCore.Mvc;

public class ArticlePageController : PageController<ArticlePage>
{
    private readonly IEnumerable<IContentAreaItemsRenderingFilter> _contentAreaFilters;
    private readonly IContentLoader _contentLoader;

    public ArticlePageController(
        IEnumerable<IContentAreaItemsRenderingFilter> contentAreaFilters,
        IContentLoader contentLoader)
    {
        _contentAreaFilters = contentAreaFilters;
        _contentLoader = contentLoader;
    }

    public IActionResult Index(ArticlePage currentPage)
    {
        var rawItems = currentPage.MainContentArea?.Items ?? Enumerable.Empty<ContentAreaItem>();

        // Apply built-in CMS 13 filters sequentially
        var filteredItems = rawItems;
        foreach (var filter in _contentAreaFilters)
        {
            filteredItems = filter.FilterItems(filteredItems);
        }

        var visibleBlocks = filteredItems
            .Select(item => _contentLoader.Get<IContent>(item.ContentLink))
            .ToList();

        var model = new ArticlePageViewModel(currentPage)
        {
            VisibleBlocks = visibleBlocks,
            HasVisibleContent = visibleBlocks.Any()
        };

        return View(model);
    }
}

Option 2: Creating a Reusable Extension Helper

To avoid repeating the foreach loop across multiple controllers and services, wrap the logic in a dedicated service or extension helper:

using EPiServer.Core;

public interface IContentAreaFilterService
{
    IEnumerable<ContentAreaItem> Filter(ContentArea? contentArea);
    bool HasVisibleItems(ContentArea? contentArea);
}

public class ContentAreaFilterService : IContentAreaFilterService
{
    private readonly IEnumerable<IContentAreaItemsRenderingFilter> _filters;

    public ContentAreaFilterService(IEnumerable<IContentAreaItemsRenderingFilter> filters)
    {
        _filters = filters;
    }

    public IEnumerable<ContentAreaItem> Filter(ContentArea? contentArea)
    {
        if (contentArea?.Items == null || !contentArea.Items.Any())
        {
            return Enumerable.Empty<ContentAreaItem>();
        }

        var items = contentArea.Items.AsEnumerable();
        foreach (var filter in _filters)
        {
            items = filter.FilterItems(items);
        }

        return items;
    }

    public bool HasVisibleItems(ContentArea? contentArea)
    {
        return Filter(contentArea).Any();
    }
}

Register the service in Program.cs or Startup.cs:

services.AddScoped<IContentAreaFilterService, ContentAreaFilterService>();

Now any controller or view model factory can check visibility cleanly:

if (_filterService.HasVisibleItems(currentPage.SidebarContentArea))
{
    // Render sidebar section
}

Related API Note: FilterAccess vs IContentAccessEvaluator

While upgrading access evaluation code, keep in mind that direct calls to FilterAccess.QueryDistinctAccessEdit() and FilterAccess.QueryDistinctAccess() are also obsolete in CMS 13. Replace direct FilterAccess static calls with the injected IContentAccessEvaluator service:

// Legacy CMS 12 call (Obsolete)
// var hasAccess = FilterAccess.QueryDistinctAccess(content, AccessLevel.Read);

// Recommended CMS 13 replacement
var hasAccess = _contentAccessEvaluator.HasAccess(content, context.User, AccessLevel.Read);

Important

• Do not swap contentArea.FilteredItems with contentArea.Items without filtering. Items bypasses visitor group personalization and permissions entirely.
• IContentAreaItemsRenderingFilter runs synchronously in memory over the loaded item collection, but the underlying content items may still need to be loaded via IContentLoader. When loading items from links, use batch loading methods like _contentLoader.GetItems(links, options) rather than looping single Get<T>() calls.
• Custom filters can be created by implementing IContentAreaItemsRenderingFilter and adding them to the DI container. This is useful if you have custom schedule, device, or geo-targeting rules outside standard Visitor Groups.
• Visitor groups only function in MVC/coupled rendering setups. If you plan to move content to Optimizely Graph for headless consumption, Visitor Groups are not indexed; use CMS 13 Content Variations and Optimizely Experimentation instead.

Links

• FAQs for Optimizely CMS v13.0.0
• Upgrade to CMS 13 from CMS 12
• Breaking changes in CMS 13

Every CMS 12 to CMS 13 upgrade I have looked at starts the same way. Someone opens the solution and starts hunting. A text search for the APIs they half-remember being removed, a scroll through appsettings.json looking for sections that no longer bind to anything, a squint at the .csproj to see which target framework it is still on, and a mental inventory of which third-party packages have a CMS 13 build yet. Then the compiler finds the rest, usually about three weeks in.

It works. It is also manual, inconsistent between whoever happens to be doing it, and it does not scale past a handful of projects. The things that slip through are rarely the obvious ones. They are the API that was merely deprecated last major and is an error in this one, the add-on package that quietly caps its dependency below CMS 13, the configuration section that still binds without complaint but no longer does anything, and the project nobody noticed is still on an older target framework.

I wanted something that would do that first pass for me, the same way every time, without needing an internet connection or a credit card. That is cms13-scan (package name OptimizelyCms13ReadinessScanner), a .NET global tool I have just published to NuGet. It reads your solution and reports what will block or complicate a CMS 13 upgrade across four places people tend to check separately: C# source, configuration, project files, and the NuGet packages you depend on.

What it does

Point it at a solution, a project, or a directory of an Optimizely CMS 12 codebase, and it reports the breaking changes, deprecated APIs, and configuration drift that will block or complicate an upgrade to CMS 13, before you start the upgrade.

cms13-scan ./MySite.sln --exclude-tests

It prints a console summary with counts of Blockers, Warnings, and Info findings, an overall readiness score, and file and line references for each finding, with a suggested fix.

Why it does not use AI

This is the bit I actually want to make the case for, because it was a deliberate choice, not a missing feature.

It would have been easy to wire this up as a thin wrapper around an LLM: dump the codebase into a prompt, ask it to find CMS 13 breaking changes, get something back. I did not want that, for a few reasons that matter more the bigger the codebase gets.

• Deterministic output - the same codebase scanned twice gives you the same findings, the same line numbers, the same score. That matters when you are comparing a baseline before and after a fix, or gating a build in CI. Non-deterministic output in a gate is worse than no gate.
• No tokens, no API key, no bill - there is nothing to meter. You are not paying per file, per scan, or per line of code. Run it a hundred times a day against a hundred solutions and the cost is the same: zero.
• Your code never leaves your machine - a lot of Optimizely solutions sit behind strict client NDAs. Sending source code to a third-party model to ask "is this obsolete" is a non-starter for plenty of teams, and rightly so. This tool parses C#, XML, and JSON locally, and only reaches the network at all if you explicitly opt into --check-packages or --check-api, and even then it is just hitting your configured NuGet feeds, not a model.
• Every finding traces back to a rule you can read - OPT13-002 is always "synchronous Find query execution", triggered by a specific member access pattern defined in rules.json. There is no "the model thought this looked risky." If a finding is wrong, you can go look at the rule, see exactly why it fired, and either fix your code or suppress that specific rule with a reason.
• It is fast - a syntax-only pass over a large solution takes seconds, because it is not making a round trip per file to an inference endpoint.

Note: none of this means AI tools are bad for migration work. They are genuinely useful for things like "rewrite this specific obsolete call to the new API" once you know where to look. This tool is for the "where do I even need to look" step, which is a static analysis problem, not a reasoning problem, and static analysis problems are better solved with a fast, deterministic, rule-based scanner.

How it works

By default the scanner parses C#, XML, and JSON files without executing anything, and it is aware of Directory.Build.props, so it picks up properties and package references defined further up the folder tree instead of reporting false "missing" findings.

There are three opt-in levels of depth:

• Syntax matching (default) - fast pattern matching against known obsolete members and namespaces. Anything that can only be confirmed by resolving the actual symbol is reported as an unverified Warning rather than a Blocker, to avoid false positives.
• --semantic - compiles your projects via MSBuild to resolve real symbols and types, which lets findings like OPT13-007 (obsolete API usage) get confirmed and escalated to Blocker, or cleared entirely. This needs the solution to already be restored.
• --check-packages / --check-api - reads your nuget.config, checks direct package references against your target CMS major version, and downloads the actual CMS 13 assemblies to check for APIs that are missing or marked [Obsolete(error: true)].

What it checks

Thirteen rules ship out of the box, covering the usual suspects for a CMS 12 to CMS 13 move:

• OPT13-001 / 011 / 012 - direct or transitive dependency on Search & Navigation (Find) packages and namespaces, which are not supported on CMS 13.
• OPT13-002 - synchronous Find query execution, like .GetResult() or SearchClient.Instance.
• OPT13-003 - ContentArea.FilteredItems, which is [Obsolete(error: true)] in CMS 13.
• OPT13-004 - deprecated FilterAccess.QueryDistinctAccess* calls.
• OPT13-005 - legacy EPiServer:Find config sections and hardcoded Graph credentials sitting in appsettings*.json or web.config.
• OPT13-006 / 009 - missing TreatWarningsAsErrors, and target frameworks that are not on .NET 10 or later.
• OPT13-007 / 013 - any [Obsolete] Optimizely API usage, and types or members that are gone outright in CMS 13 assemblies (needs --semantic).
• OPT13-008 - ISiteDefinitionRepository / SiteDefinition usage, flagged for an application-model review rather than as a hard blocker.
• OPT13-010 - third-party package dependencies that are incompatible with, or undetermined for, CMS 13.

Each rule carries a severity (Blocker, Warning, or Info), and the readiness score is calculated off the breadth of distinct rules triggered rather than the raw count of occurrences, so one file with fifty of the same obsolete call does not tank the score harder than fifty files each with one different problem:

Score = 100 - (distinct Blocker rules x 20) - (distinct Warning rules x 8) - (distinct Info rules x 2)

If a built-in rule does not fit your codebase, or you want to add your own, --rules <file> lets you merge or override rules using the same kinds the built-ins use (ProjectPackageReference, MemberAccessPattern, ProjectFileMustContain, IdentifierUsage, ProjectTargetFramework). --list-rules prints the effective set so you can see exactly what is active.

Install it

dotnet tool install --global OptimizelyCms13ReadinessScanner

Or scoped to a repo with a tool manifest:

dotnet new tool-manifest
dotnet tool install OptimizelyCms13ReadinessScanner
# run via: dotnet cms13-scan

It targets .NET 8 but ships with RollForward=Major, so it runs fine on a machine with only .NET 10 installed. The solution you are scanning can be on any framework, since the scanner inspects it out of process.

Using it

Quick first look, syntax only, no restore needed:

cms13-scan ./MySite.sln --exclude-tests

Full accurate run, after dotnet restore:

cms13-scan ./MySite.sln --semantic --check-packages --check-api --exclude-tests --no-fail --output-markdown cms13-report.md

CI build gating against a baseline, so only new findings fail the build:

cms13-scan ./MySite.sln --baseline baseline.json --output-sarif cms13.sarif

The SARIF output plugs straight into GitHub code scanning or Azure DevOps PR annotations, so findings show up inline on a pull request instead of buried in a build log. Exit codes are plain: 0 clean, 1 new blockers found, 2 path does not exist.

Findings can also be suppressed inline when you have a reason to:

// cms13-scan:disable OPT13-003
// cms13-scan:disable-next-line OPT13-002

Suppressed findings are dropped from the score and the exit code, but stay listed in the report for visibility, so a suppression is not the same as sweeping it under the rug.

What this is not

I want to be direct about this rather than let the tool oversell itself: cms13-scan is single-purpose. It finds and reports breaking changes. It does not rewrite your code, it does not perform the upgrade, it does not touch your Opti ID, Graph, or hosting configuration, and it is not aware of your specific solution's architecture or customizations beyond what a static scan can see.

Optimizely has its own homebrew migration and analysis tooling for CMS upgrades, backed by people who do this for a living and have seen far more upgrade paths than a side-project scanner ever will. If you are planning an actual CMS 12 to CMS 13 migration, especially anything non-trivial, get in touch with Optimizely directly so you have access to the right tools, guidance, and expertise for the full job. Use cms13-scan as a quick, free, local first pass to scope the size of the problem before that conversation, not as a replacement for it.

Compatibility

• Requires the .NET 8 SDK or newer to install and run.
• Scans CMS 12 codebases targeting CMS 13 by default (--cms-target-major defaults to 13, but can be changed).
• Semantic and API checks need the target solution already restored.

Links

• GitHub repository: OptimizelyCms13ReadinessScanner
• NuGet package: OptimizelyCms13ReadinessScanner

It is MIT licensed, so pull requests, new rules, and bug reports are all welcome on GitHub. If it saves your team even a day of manual grepping before an upgrade kickoff, it has done its job.

When teams start planning their upgrade to Optimizely CMS 13, one common misconception causes unnecessary panic: the assumption that adopting Visual Builder forces your site into a headless architecture or requires rendering every page layout through Optimizely Graph GraphQL queries.

While CMS 13 is an opinionated, Graph-first platform for search, content modeling, and headless delivery, Visual Builder does not require Graph for frontend rendering. If your site runs on traditional ASP.NET Core MVC, Optimizely CMS 13 provides a suite of native Razor tag helpers that render experiences, sections, rows, columns, and components directly on the server.

This allows you to give editors the full Visual Builder drag-and-drop experience, complete with real-time preview and interactive property highlighting, while preserving your existing MVC controllers, Razor views, and server-side performance.

On-Page Edit (OPE) in CMS 13: Disabled by Default, Not Removed

A related point of confusion is what happens to On-Page Edit (OPE). Visual Builder is the default editing interface in CMS 13, and classic OPE is disabled out of the box. However, it is not permanently gone. If your editorial team prefers the classic in-context editing view alongside Visual Builder, developers can re-enable it in Program.cs or Startup.cs:

using EPiServer.Cms.Shell.UI.Configurations;

services.Configure<CmsFeatureOptions>(options =>
{
    options.SectionsVisibility.OnPageEditing = true;
});

Even with OPE enabled, Visual Builder is the primary tool for structured layouts in CMS 13. Here is how that layout composition is structured under the hood.

Understanding the Composition Tree

Visual Builder introduces Experiences and Sections to structure layouts. Under the hood, an experience is organized as a hierarchical composition tree:

• Experience (Root): The top-level composition page container (inheriting from ExperienceData).
• Section (Grid): A structural block defining the layout grid.
• Row: A horizontal layout row inside a section.
• Column: A vertical column cell within a row.
• Component: An individual block or element placed inside a column.

Optimizely CMS 13 maps this tree directly to five dedicated tag helpers: <epi-outline>, <epi-grid>, <epi-row>, <epi-column>, and <epi-component>.

Setup and Registration

First, verify that your project references the tag helpers package:

dotnet add package EPiServer.CMS.AspNetCore.TagHelpers

Next, register the tag helper services in your Program.cs or Startup.cs:

public void ConfigureServices(IServiceCollection services)
{
    // Register standard CMS dependencies
    services.AddCms();

    // Register Visual Builder tag helpers
    services.AddCmsTagHelpers();
}

Finally, expose the tag helpers to your Razor views by adding the directive to Views/_ViewImports.cshtml:

@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@addTagHelper *, EPiServer.Cms.AspNetCore.TagHelpers

Rendering an Experience in Razor

The simplest way to render an entire Visual Builder composition is wrapping the hierarchy in an <epi-outline> tag helper. Here is an example view for an experience page model:

@model IPageViewModel<ExperienceData>

<main class="site-main">
    <epi-outline class="experience-wrapper" experience="@Model.CurrentPage">
        <epi-grid>
            <epi-row>
                <epi-column>
                    <epi-component />
                </epi-column>
            </epi-row>
        </epi-grid>
    </epi-outline>
</main>

Here is what happens during rendering:

• experience attribute: Accepts your ExperienceData model instance. If the model is null or contains no composition, the helper renders nothing.
• Template resolution: For each component inside a column, the rendering engine resolves the appropriate block view using standard Optimizely MVC template resolution conventions.
• Automatic edit attributes: In edit mode, the tag helpers automatically inject required data-epi-block-id attributes into the DOM. Editors can select, move, and edit blocks in Visual Builder without needing manual helper calls.

Customizing HTML Output Elements

By default, all composition tag helpers emit standard <div> tags. To keep your frontend semantic, use the tag-name attribute to customize the generated HTML element for each tier:

<epi-outline tag-name="section" experience="@Model.CurrentPage">
    <epi-grid tag-name="div" class="container">
        <epi-row tag-name="div" class="row">
            <epi-column tag-name="article" class="col-md-8">
                <epi-component />
            </epi-column>
            <epi-column tag-name="aside" class="col-md-4">
                <epi-component />
            </epi-column>
        </epi-row>
    </epi-grid>
</epi-outline>

Mapping Visual Builder Display Settings to CSS Classes

Visual Builder allows editors to configure display settings (such as margins, padding, or theme colors) through key-value dropdowns in the CMS UI. You can map these settings directly to CSS utility classes in Razor using the <epi-styles> tag helper:

<epi-outline experience="@Model.CurrentPage">
    <epi-styles class="layout-node">
        <epi-style name="margin" value="top" class="mt-4" />
        <epi-style-map name="spacing">
            <map value="compact" class="p-2" />
            <map value="comfortable" class="p-4" />
            <map value="spacious" class="p-6" />
        </epi-style-map>
    </epi-styles>

    <epi-grid>
        <epi-row>
            <epi-column>
                <epi-component />
            </epi-column>
        </epi-row>
    </epi-grid>
</epi-outline>

The <epi-styles> element produces no markup of its own. It acts as a configuration block instructing child composition nodes how to transform Visual Builder settings into CSS classes on the emitted HTML elements.

When to Use MVC Tag Helpers vs. Optimizely Graph

Important

• On-Page Edit (OPE) is disabled by default in CMS 13, but can be restored using options.SectionsVisibility.OnPageEditing = true under CmsFeatureOptions.
• While server-side MVC rendering does not require Graph for HTML generation, Graph is still a mandatory licensed component in CMS 13. Features like Content Manager search, auto-translation, and content variations still depend on Graph running in the background.
• Tag helpers are the supported direction for coupled rendering in modern .NET. Microsoft has stopped active investment in HTML helpers (such as Html.PropertyFor), making tag helpers the recommended standard for long-term maintainability.
• Ensure your component partial views do not make synchronous blocking database calls. The entire Visual Builder composition tree is resolved during page execution, so keep component rendering clean and async.

Links

• Render an experience with tag helpers
• Render properties with tag helpers
• Add editing attributes in CMS 13
• 2026 Optimizely CMS 13 GA release notes

If you are planning an upgrade to Optimizely CMS 13, one of the biggest architectural shifts is that Optimizely Search & Navigation (EPiServer.Find) is completely unsupported. It is not just deprecated; the packages will not run on CMS 13. Every site moving to CMS 13 must replace Find with Optimizely Graph.

The good news is that Optimizely provides a dedicated C# query package for CMS 13 (Optimizely.Graph.Cms.Query) that offers a fluent API structured very similarly to the old Find client. However, there are significant changes under the hood, particularly around package names, configuration keys, dependency injection, and a move from synchronous to asynchronous query execution.

Here is a step-by-step walkthrough to help you migrate your codebase cleanly.

Package Replacements

First, remove all legacy Find and related packages from your project files:

<!-- Remove legacy Find packages -->
<PackageReference Remove="EPiServer.Find" />
<PackageReference Remove="EPiServer.Find.Cms" />
<PackageReference Remove="EPiServer.Find.Framework" />
<PackageReference Remove="Wangkanai.Detection" />

Next, install the Optimizely Graph packages for CMS 13:

dotnet add package Optimizely.Graph.Cms.Query
dotnet add package Optimizely.Graph.AspNetCore

Optimizely.Graph.Cms.Query provides the strongly-typed LINQ-style query builder, while Optimizely.Graph.AspNetCore handles middleware and client lifecycle integration.

Configuration Changes in appsettings.json

Remove the legacy EPiServer:Find section from appsettings.json:

// Remove this block
"EPiServer": {
  "Find": {
    "ServiceUrl": "https://...",
    "DefaultIndex": "your_index_name"
  }
}

Replace it with the new Optimizely:Graph section:

"Optimizely": {
  "Graph": {
    "GatewayAddress": "https://cg.optimizely.com",
    "AppKey": "YOUR_APP_KEY",
    "Secret": "YOUR_SECRET_KEY",
    "SingleKey": "YOUR_SINGLE_KEY"
  }
}

On local environments, populate these keys from your Graph portal. In Optimizely DXP, these environment variables are provisioned automatically at deployment time.

Service Registration and Middleware

In your Startup.cs or Program.cs, swap the service registrations and middleware:

// Remove legacy Find calls:
// services.AddFind();
// services.AddDetection();
// app.UseDetection();

// Add Optimizely Graph:
services.AddContentGraph();
services.AddGraphContentClient();

// Add Graph tracking middleware
app.UseGraphTrackingScripts();

Namespace Updates

Find queries used namespaces scattered across EPiServer.Find.*. In CMS 13, the majority map directly to Optimizely.Graph.Cms.Query:

You can remove older references such as EPiServer.Find.Framework.Statistics and EPiServer.Find.Helpers.Text as they are no longer used.

Query Rewriting: Client and Execution Model

The single most impactful code change is how queries execute. Find allowed synchronous calls like .GetContentResult() or .GetResult(). Optimizely Graph is strictly asynchronous and relies on dependency injection rather than static singleton access.

1. Client Dependency Injection

Instead of SearchClient.Instance or injecting IClient, inject IGraphContentClient:

public class SearchPageController : PageController<SearchPage>
{
    private readonly IGraphContentClient _graphClient;

    public SearchPageController(IGraphContentClient graphClient)
    {
        _graphClient = graphClient;
    }

    // ...
}

2. Querying Content with GetAsContentAsync

In Find, fetching full content items typically looked like this:

// Legacy Find (Synchronous)
var results = SearchClient.Instance.Search<ArticlePage>()
    .For(query)
    .InField(x => x.Title)
    .Filter(x => x.Category.Match("News"))
    .Take(10)
    .GetContentResult();

In Optimizely Graph for CMS 13, use QueryContent<T>() and GetAsContentAsync():

// Optimizely Graph (Async)
var results = await _graphClient.QueryContent<ArticlePage>()
    .SearchFor(query)
    .UsingFullText()
    .Where(x => x.Category == "News")
    .Limit(10)
    .GetAsContentAsync();

GetAsContentAsync() returns an IGetAsContentResult<T> that implements IEnumerable<T>, delivering fully resolved CMS content models without requiring extra mapping layers.

3. Dynamic Filtering with BuildFilter

In Find, dynamic search criteria were typically composed by chaining .Filter() calls. In the Graph C# SDK, use BuildFilter<T>() to assemble conditional logic dynamically:

var filterBuilder = _graphClient.BuildFilter<ArticlePage>()
    .And(x => x.Name.FilterStartsWith("Tech"));

if (!string.IsNullOrEmpty(selectedAuthor))
{
    filterBuilder = filterBuilder.And(x => x.Author.Eq(selectedAuthor));
}

var results = await _graphClient.QueryContent<ArticlePage>()
    .Where(filterBuilder)
    .GetAsContentAsync();

4. Faceted Navigation

Facets work differently in Graph. When users filter by an author, you often want the facet counts for all other authors to remain visible so users can switch options easily. The Facet() extension accepts a filters parameter directly for this purpose:

var results = await _graphClient.QueryContent<ArticlePage>()
    .SearchFor(query)
    .UsingFullText()
    .Facet(x => x.Author, filters: [selectedAuthor])
    .GetAsContentAsync();

var authorFacet = results.Facets?.GetFacet(x => x.Author);

Important

• Do not mix the platform upgrade with the search migration. Upgrade your project to CMS 13 first, verify that it compiles and starts, and then execute the Find to Graph migration on a dedicated Git branch.
• Audit all synchronous helper methods, extensions, and custom view models. Because Graph requires await for execution, synchronous wrappers (such as .GetAwaiter().GetResult()) can cause thread pool starvation under production loads on ASP.NET Core. Convert calling methods to async up the stack.
• Remember that CMS 13 introduces a breaking schema change in Graph compared to CMS 12. If you are already testing Graph on CMS 12, provision a separate Graph instance for your CMS 13 deployment slot to avoid corrupting your production index. Read more about this here.
• Property indexing modes matter for query performance. Mark fields that are only displayed in results (and never searched or filtered) with the [GraphProperty(PropertyIndexingMode.OutputOnly)] attribute to minimize Graph indexing overhead.

Links

• Migrate an Alloy site from CMS 12 to CMS 13
• Quick start with the Graph C# SDK
• Aggregate Optimizely Graph results with the C# SDK
• Upgrade to CMS 13 from CMS 12

In September 2025, I wrote about updating your robots.txt file to explicitly allow AI bots like GPTBot, ClaudeBot, PerplexityBot, and OAI-SearchBot. Back then, the main challenge was simply granting access: deciding whether to allow training crawlers, search indexing bots, or a mix of both.

A year later, the conversation has shifted. Allowing bots in robots.txt is only table stakes. The real question today is: once you let them in, how often do they visit, what are they reading, and does that traffic convert into actual user referrals? This discipline is known as Generative Engine Optimization (GEO), and Optimizely CMS 13 now builds native tools to measure and optimize for it.

The Evolution from Access to Measurement

Allowing an AI user-agent in robots.txt tells an LLM crawler it is legally and technically welcome. What it does not tell you is whether the crawler understood your content structure, indexed your canonical answers, or simply scrapped your raw HTML without citing your brand.

Here is what the shift looks like in practice:

• 2025 (Permission): Defining user-agent rules in robots.txt to prevent AI engines from silently bypassing your site.
• 2026 (Visibility & Analytics): Tracking crawl frequency, measuring referral rates, and observing which specific pages AI platforms extract data from.
• 2026 (Optimization): Structuring content specifically for AI ingestion using dedicated schema, Q&A fields, and entity models.

Tracking AI Crawlers with GEO Analytics & Agent Visibility

In Optimizely Reporting and Optimizely Analytics, the platform tracks incoming bot traffic categorized specifically by AI engine rather than burying them inside generic organic traffic numbers.

The core metric introduced here is the Crawl-to-Refer Ratio:

Note: While earlier preview documentation referred to the "GEO Analytics dashboard", newer environments direct teams to the Agent Visibility dashboard inside Optimizely Analytics. This view enriches crawler hits with request intent and Optimizely Opal / Mark facet insights.

Native AI Optimization Features in CMS 13

Beyond tracking bots, Optimizely CMS 13 introduces dedicated agents and metadata models to help content rank in generative engine answers:

1. Schema and Answers Agent

Generative search engines prefer extractable, atomic facts over sprawling multi-paragraph layouts. The Schema and Answers Agent automatically evaluates content relationships and suggests structured metadata, FAQ schemas, and direct Q&A blocks so LLMs can cleanly parse answers.

2. GEO Recommendations Agent

Similar to traditional on-page SEO checkers, this agent runs checks against your draft content in Visual Builder, evaluating your pages against known generative search visibility signals before publishing.

3. Optimizely Graph Metadata Integration

Because Optimizely Graph indexes the composition model of your pages and blocks, it surfaces structured metadata contracts (such as _itemMetadata and _assetMetadata) directly. When AI aggregators and agents query your GraphQL endpoint or rendered pages, the data schema is unambiguous.

Updating Your Strategy: What to Do Next

1. Audit your current robots.txt: Verify that recent AI crawlers are still permitted. If you used the balanced template from last year (allowing search bots while blocking training crawlers), verify that your directives reflect current user-agent names.
2. Review the Agent Visibility Dashboard: Check which pages have the highest crawl volume from OpenAI and Perplexity. Look for high crawl counts paired with low citation referrals.
3. Add Structured Q&A Blocks: Update key commercial and technical documentation pages with concise summary definitions and FAQ schema markup.
4. Leverage SEOBOOST add-on: If you are managing technical metadata, canonical tags, and robots directives on Optimizely CMS, use automated metadata tooling so headers and crawler rules stay aligned across multi-site instances.

Important

• Do not rely entirely on robots.txt for compliance. Some rogue or emerging AI scrapers ignore standard robots directives. For strict enforcement, pair your robots.txt file with Web Application Firewall (WAF) bot rules on Optimizely DXP or Cloudflare.
• The legacy GEO Analytics dashboard was grandfathered for early access instances. Modern CMS 13 setups use the Agent Visibility dashboard in Optimizely Analytics for richer crawler telemetry.
• Generative search engines value freshness and canonical accuracy. If your content updates frequently, ensure your XML sitemap and Optimizely Graph index sync without delay so bots do not reference stale answers.

Links

• How to Allow AI Bots in Your robots.txt File (2025 Edition)
• Why upgrade to CMS 13?
• GEO Analytics for CMS (PaaS)
• SEOBOOST for Optimizely CMS

If you're planning your Optimizely CMS 13 upgrade and you already run Optimizely Graph on your CMS 12 site, there's one detail that catches almost everyone off guard: you cannot point your CMS 13 environment at the same Graph instance your live CMS 12 site is using. Not temporarily, not just for testing. CMS 13 ships a breaking change to the Graph schema, and a CMS 12 site and a CMS 13 site cannot share a Graph instance without migrating the schema first.

This isn't an optional step you can defer. Graph is required to use CMS 13's full capabilities, including Content Manager and Experiences, so for any site already running Graph on CMS 12, migrating it is part of the CMS 13 upgrade itself, not a follow-up task.

Why This Happens

CMS 13 changes what Graph indexes and how it's shaped. Experiences, Sections, and Visual Builder's composition model change the object graph that gets synced from your CMS content tree, so the schema CMS 13 expects Graph to serve is different from the one CMS 12 populates. Point a CMS 13 site at a CMS 12 Graph instance (or vice versa) and queries either fail outright or quietly return the wrong shape of data.

That's why the upgrade guidance is blunt about it: treat the Graph migration as a required part of moving to CMS 13, not a nice-to-have cleanup step you can do later.

Two Ways to Handle the Migration

You have two supported paths. Which one you pick depends mostly on whether your site is live and how much downtime you can tolerate.

Option 1: Provision a New Graph Instance (Recommended, Zero Downtime)

Your live CMS 12 site keeps using its existing Graph instance while your CMS 13 deployment slot uses a brand new one. Graph never goes down for either version.

1. Log in to the DXP Management Portal at https://paasportal.episerver.net.
2. Open your organization and project, then go to the API tab and open Optimizely Graph Service Configurations. Click Prepare for CMS 13 to provision a separate Graph instance.
3. Deploy CMS 13 through a deployment slot. The slot uses the new Graph credentials while production keeps using the old ones.
4. Validate the slot against the CMS 13 schema without touching your live CMS 12 Graph data.
5. Swap the slot into production. Production automatically picks up the new CMS 13 Graph credentials.

The old CMS 12 Graph instance isn't deleted immediately. It's retired in two stages so anything still pointing at the old keys has time to surface:

• Stage 1 - Key rotation (soft delete): runs once all linked front-end environments are confirmed on the new key and a grace period (default seven days) has elapsed since that confirmation — or, if there are no linked front-end environments, seven days after go-live. This disables the old keys, so anything still using them starts failing visibly.
• Stage 2 - Hard delete: the old Graph instance is removed a further 30 days after Stage 1.

That visible failure in Stage 1 is a feature, not a bug. It's your forcing function for finding every forgotten front end, webhook, or scheduled job that still has the old single key hardcoded somewhere.

Option 2: Smooth Rebuild on Your Existing Instance (Downtime Required)

If you'd rather keep your existing Graph instance and credentials (so external consumers never need to update anything), you can migrate the schema in place instead. This requires taking the site offline.

1. Put the site behind a static maintenance page.
2. In CMS, go to Settings > Smooth Rebuild, open Smooth Rebuild Settings, and click Start.
3. Graph creates a new deployment slot (green) alongside the current one (blue) and starts syncing content into it.
4. Test the green slot before promoting it. Use the Optimizely Graph playground (GraphiQL) with the New toggle enabled, or add the cg-query-new: true header to your GraphQL requests to target it directly.
5. Deploy CMS 13 through a deployment slot once the rebuild has finished syncing.
6. Promote the green slot to live.

cg-query-new: true

Because the CMS 13 schema change is breaking, you can't use Graph's normal zero-downtime read-only or read-write slot modes here. The site has to be fully offline behind the maintenance page for the duration of the rebuild.

Important

• If you haven't implemented Optimizely Graph on your CMS 12 project at all, none of this applies to you. Follow the standard DXP upgrade path through Integration, Preproduction, and Production.
• Run whichever path you choose in Integration and Preproduction first. You need to know how long the sync or rebuild actually takes before you size a Production maintenance window around it.
• Audit anything with a hardcoded Graph single key (Next.js front ends, webhooks, scheduled jobs) before you start. Key rotation will break them loudly, which is useful, but you'd rather know in advance than get paged for it.
• Local development config (GatewayAddress, AppKey, Secret, SingleKey in appsettings.json or web.config) is separate from what DXP auto-provisions on deployment. Don't carry your CMS 12 Graph configuration into your CMS 13 deployment and assume it'll just work.

Which Option Should You Pick?

Either way, don't treat this as a side detail of the CMS 13 upgrade. It's the part of the migration most likely to take down search, navigation, or personalization on your site if you discover it mid-deployment instead of during planning.

Links

• Migrate from CMS 12 to CMS 13 with Optimizely Graph
• Upgrade to CMS 13 from CMS 12
• Smooth Rebuild in Optimizely Graph
• Breaking changes in CMS 13