Blog posts by Connor Fortin

Blog posts by Connor Fortin2026-06-24T17:58:56.0000000Zhttps://world.optimizely.com/blogs/connor-fortin/ Optimizely World Automated Search & Navigation to Graph Migration with Claude CodeA Claude Code plugin that scans your S&N codebase, applies Graph SDK transformations, and validates the result. Install once, run one command. <div style="display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 32px;">CMS 13 Optimizely Graph Migration Claude Code Automation Search & Navigation</div> <div style="background: linear-gradient(135deg,#f0f4ff 0%,#e8f0fe 100%); border: 1px solid #93c5fd; border-left: 4px solid #2563eb; border-radius: 8px; padding: 10px 28px; margin: 0 0 40px;"> <h3 style="margin-top: 0;">TL;DR</h3> <ul> <li>The cg-migrate Claude Code plugin automates the Search & Navigation to Graph SDK migration. It scans your .NET solution for every Find API usage, rewrites the code to use Optimizely.Graph.Cms.Query, and validates the result by building the project and attributing compiler errors back to the specific transformation that caused them.</li> <li>Five skills cover the full workflow: /migrate-all runs the entire pipeline end-to-end, or use the individual skills for more control: /migrate-scan discovers all S&N usage and classifies complexity, /migrate-transform rewrites the code, /migrate-validate checks the build, and /migrate-map handles one-off translations.</li> <li>It understands your codebase structure. The scan traces dependency graphs through wrapper classes and DI registrations, so indirect consumers of Find are identified too.</li> <li>You keep control over the hard decisions. When a pattern has no direct Graph equivalent (like UnifiedSearch or custom FilterForVisitor implementations), the plugin generates a decisions file and pauses for your input before continuing.</li> <li>Install with two commands and the plugin loads on every Claude Code session automatically.</li> </ul> </div> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">1. Why This Plugin Exists</h2> The <a href="/link/5ffa0c0d7b184f049358e62d7fcad94f.aspx">Graph SDK blog post</a> on Optimizely World covers how to write queries with Optimizely.Graph.Cms.Query. If you have not read it yet, start there. It walks through Where(), SearchFor(), Facet(), and the rest of the API that replaces Search & Navigation. What the blog post does not cover is the mechanical work of actually migrating a real codebase. A typical Optimizely solution has Search & Navigation calls spread across dozens of files. Some are straightforward Search<T>().Filter().GetResult() chains. Others are wrapped behind repository classes, injected through DI containers, or built up conditionally with .OrFilter() composition. Finding all of that, understanding the dependency graph, and rewriting it file by file takes time that could be spent on the parts of a CMS 13 migration that genuinely require human judgment. The cg-migrate plugin handles the mechanical part. It is a set of Claude Code skills that scan your solution, apply the known API mappings from the Graph SDK blog post, flag the patterns that need human decisions, and validate the result against the compiler. You stay in control of architecture questions. The plugin handles the find-and-replace at scale. <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">2. Getting Started</h2> <h3>Prerequisites</h3> You need Claude Code installed and a .NET solution that currently uses the Search & Navigation (EPiServer Find) SDK. Before running the migration, check out a dedicated branch with no pending changes. The solution should build cleanly and all tests should pass. This gives the plugin a clean baseline so it can distinguish migration-introduced errors from pre-existing issues. <h3>Installation</h3> Run these two commands in Claude Code: <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">/plugin marketplace add episerver/content-graph-sdk-migrations /plugin install cg-migrate@content-graph-sdk-migrations</pre> The plugin loads automatically on every subsequent Claude Code session. No configuration files to edit. <h3>What Gets Installed</h3> The plugin adds five slash commands to your Claude Code session: <table style="width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.9rem;"> <thead> <tr> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Command</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Purpose</th> </tr> </thead> <tbody> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-all</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Run the full migration pipeline end-to-end: scan, transform, validate, and fix</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-scan</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Discover all S&N usage across the solution and produce a migration manifest</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-map</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Translate a single file or code snippet from S&N to Graph SDK</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-transform</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Apply transformations to all files identified by the scan</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-validate</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Build the project and map each compiler error back to the transformation that caused it</td> </tr> </tbody> </table> <h3>Three Ways to Use the Plugin</h3> You do not have to use all five commands. Pick the approach that fits where you are in your migration: <table style="width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.9rem;"> <thead> <tr> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Approach</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Commands</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">When to use</th> </tr> </thead> <tbody> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Full pipeline</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-all</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">You want to migrate the entire solution end-to-end in one run. The command handles scan, transform, validate, and build-fix phases automatically, pausing only for manual decisions.</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Step by step</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-scan → /migrate-transform → /migrate-validate</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">You want to review the scan report before transforming, re-run a single phase after making manual edits, or iterate on specific files without restarting the full pipeline.</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">One-off translation</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">/migrate-map</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">You want to translate a single file or code snippet, understand how a specific S&N pattern maps to the Graph SDK, or handle a file individually before or after a larger migration run.</td> </tr> </tbody> </table> The rest of this post covers each approach in detail. If you just want to get started, skip to section 3 for the full pipeline or section 5 for one-off translations. <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">3. Running the Full Migration</h2> The fastest way to migrate is /migrate-all. It orchestrates the entire pipeline in a single invocation: <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">/migrate-all --project path/to/YourSolution.sln</pre> If you omit --project, the plugin searches for .sln files in the current directory. <h3>What Happens</h3> The command runs six phases sequentially: Phase 1: Scan. Invokes /migrate-scan to discover all Find SDK usage, trace dependency graphs, and classify each pattern by complexity. If no migration targets are found, the command stops early. Phase 2: Confirm. Presents a summary of what will be transformed automatically and what will require manual decisions, then pauses for your confirmation before making any changes. Phase 3: Transform. Invokes /migrate-transform to apply all known API mappings, swap NuGet packages, and flag items for manual review. Phase 4: Validate. Invokes /migrate-validate to build the project and attribute compiler errors to specific transformation rules. If errors are found, it automatically retries the transformation on the failed files for a second pass. Phase 5: Build & Fix. Rebuilds the project and iteratively fixes remaining compiler errors that have clear automated solutions, such as CS0266 type mismatches, CS1061 missing members, CS0246 unknown types, and NuGet version conflicts. Errors that require business logic decisions are deferred for you to handle manually. Phase 6: Report. Generates a comprehensive migration report at .cg-migrations/migrate-all/ that ties together the results from every phase: targets scanned, files transformed, errors fixed, and remaining manual items with prioritized next steps. The final report classifies the migration status as Complete (all errors resolved), Partial (some errors remain), or Nothing to migrate (no targets found). <div style="border-left: 4px solid #2563eb; border-radius: 4px; padding: 16px 20px; margin: 20px 0; font-size: 0.93rem; background: #dbeafe;">Tip Use /migrate-all for the typical workflow. The individual skills (/migrate-scan, /migrate-transform, /migrate-validate) are still available when you need to re-run a specific phase or want more control over the process. </div> <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">4. Scanning Your Codebase</h2> If you want to inspect the migration scope before committing to a full run, or if you need to re-run just the scan phase, use /migrate-scan directly: <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">/migrate-scan --project path/to/YourSolution.sln</pre> If you omit --project, the plugin searches for .sln files in the current directory. The scan runs in four phases: Phase 1: NuGet Detection. The scan parses .csproj files to find which projects reference EPiServer.Find packages and what versions they use. Phase 2: Direct Reference Scan. Using regex patterns from a built-in registry of 50+ S&N API patterns, the scan locates every file that calls into the Find SDK. Each match is categorized by type (filtering, facets, sorting, search, DI registration, etc.). Phase 3: Dependency Graph Tracing. This is where the scan goes beyond simple text search. It follows constructor injection, DI registrations, and wrapper class hierarchies up to 5 hops deep. If you have a SearchService that wraps IClient and a SearchController that injects SearchService, both get flagged as migration targets even though only SearchService contains direct Find API calls. Phase 4: Complexity Classification. Every identified pattern gets one of three labels: <table style="width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.9rem;"> <thead> <tr> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Classification</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Meaning</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Example</th> </tr> </thead> <tbody> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">direct-swap</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">1:1 Graph SDK equivalent exists</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">.Filter() to .Where(), .Take() to .Limit()</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">pattern-rewrite</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Needs restructuring but the approach is known</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">.OrFilter() composition to BuildFilter<T>().Or()</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">manual</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">No automated equivalent, needs human decision</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">UnifiedSearch, custom FilterForVisitor</td> </tr> </tbody> </table> <h3>Scan Output</h3> The scan produces a console summary with statistics and a detailed markdown report at .cg-migrations/migrate-scan/scan-report.md. The report includes every target file, the specific patterns found, the dependency tree, and the complexity breakdown. <div style="border-left: 4px solid #2563eb; border-radius: 4px; padding: 16px 20px; margin: 20px 0; font-size: 0.93rem; background: #dbeafe;">Tip Add .cg-migrations/ to your .gitignore. This directory is for migration artifacts and should not be committed. </div> <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">5. Translating Individual Queries</h2> For one-off translations or to understand how a specific pattern maps to the Graph SDK, use /migrate-map: <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">/migrate-map</pre> Point it at a file or paste a code snippet. The skill applies 17 translation rules covering the full S&N API surface. <h3>Before and After</h3> <div style="margin: 16px 0;"> <div style="font-size: 0.75rem; font-weight: bold; text-transform: uppercase; letter-spacing: 1px; padding: 6px 14px; border-radius: 8px 8px 0 0; color: #fff; background: #ef4444;">Before - Search & Navigation</div> <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 0px 0px 8px 8px; padding: 0.5rem; overflow-x: auto; margin: 0px 0px 16px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">var result = searchClient.Search<ArticlePage>() .For("chocolate cake") .InField(x => x.Title, 3.0) .InField(x => x.Summary, 2.0) .Filter(x => x.Category.Match("Dessert")) .Filter(x => x.IsPublished.Match(true)) .TermsFacetFor(x => x.Category) .OrderByDescending(x => x.PublishDate) .Take(10) .Skip(20) .GetResult();</pre> <div style="font-size: 0.75rem; font-weight: bold; text-transform: uppercase; letter-spacing: 1px; padding: 6px 14px; border-radius: 8px 8px 0 0; color: #fff; background: #16a34a;">After - Graph SDK</div> <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 0px 0px 8px 8px; padding: 0.5rem; overflow-x: auto; margin: 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">var result = await _graphClient .QueryContent<ArticlePage>() .SearchFor("chocolate cake") .UsingField(x => x.Title, boost: 3) .UsingField(x => x.Summary, boost: 2) .Where(x => x.Category == "Dessert" && x.IsPublished) .Facet(x => x.Category) .OrderBy(x => x.PublishDate, OrderDirection.Descending) .Limit(10) .Skip(20) .IncludeTotal() .GetAsContentAsync();</pre> </div> The /migrate-map skill is useful for building intuition about the mapping rules before running a full transformation, and for handling files you want to review individually. <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">6. Transforming the Full Codebase</h2> Once you have reviewed the scan report and understand the scope, run the full transformation: <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">/migrate-transform --project path/to/YourSolution.sln</pre> You can optionally pass the scan report path if you have already run /migrate-scan: <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">/migrate-transform --project path/to/YourSolution.sln --scan-report .cg-migrations/migrate-scan/scan-report.md</pre> <h3>How the Transform Works</h3> The transform runs in six phases: Phase 1: Decision Resolution. For every pattern classified as manual in the scan, the transform generates a decisions file at .cg-migrations/migrate-decisions.md. This file groups patterns and presents strategy options. The plugin pauses here and asks you to choose a strategy for each group before continuing. Example decision groups and strategies: <table style="width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.9rem;"> <thead> <tr> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Pattern Group</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Suggested Strategy</th> </tr> </thead> <tbody> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">UnifiedSearch (searches across multiple content types)</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">type-specific-queries (create separate QueryContent<T>() per type)</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">ContentIndexer / .Track() calls</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">remove (comment out, no Graph equivalent for direct indexing)</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Custom site/visitor filters</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">custom-implementation (you provide the replacement logic)</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">.UsingSynonyms()</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">per-filter-synonym (move to .Match("value", SynonymSlot.One))</td> </tr> </tbody> </table> Phase 2: NuGet Package Setup. Adds Optimizely.Graph.Cms.Query to the relevant projects and tracks the S&N packages for removal. Phase 3: Code Transformation. Each file gets 13 transformation steps applied in sequence: namespace updates, DI registration changes, query entry points, full-text search, filtering, sorting, pagination, facets, projections, execution (all made async), result access patterns, manual pattern strategies, and cleanup of orphaned using statements. Phase 4: Cleanup. Removes using EPiServer.Find statements that are no longer needed. Phase 5: Build Validation. Runs dotnet build and auto-fixes common issues like NuGet conflicts and generic constraint mismatches (the Graph SDK requires where T : class, IContentData rather than just IContentData). Iterates up to 2 cycles. Phase 6: Reporting. Generates a transform report at .cg-migrations/migrate-transform/transform-report.md with per-file results. <div style="border-left: 4px solid #f59e0b; border-radius: 4px; padding: 16px 20px; margin: 20px 0; font-size: 0.93rem; background: #fef3c7;">The decisions file persists across runs If you run /migrate-transform again, it reads your previous decisions. You can edit the file directly to change strategies for specific patterns or files. </div> <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">7. Validating the Result</h2> After the transform completes, run validation: <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">/migrate-validate --project path/to/YourSolution.sln</pre> The validation phase does more than just run dotnet build. It parses every compiler error, matches it against a built-in lookup table of known migration-related error signatures, and attributes each failure to the specific transformation rule that likely caused it. <h3>Validation Output</h3> The report separates errors into three buckets: <table style="width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.9rem;"> <thead> <tr> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Bucket</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">Meaning</th> </tr> </thead> <tbody> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Migration-caused (high confidence)</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">File was transformed AND error matches a known migration pattern</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Possibly migration-related (medium confidence)</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Error matches a known cause but the file was not directly transformed</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Pre-existing / out-of-scope</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Error does not match any migration pattern</td> </tr> </tbody> </table> Each error includes the file path, line number, error code, message, and the likely cause with a suggested fix. <h3>Example Error Attribution</h3> <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;">CS1061 in SearchService.cs:42 'IContentQuery<ArticlePage>' does not contain a definition for 'TotalMatching' Likely cause: Rule 11 (Result Access) Suggested fix: Add .IncludeTotal() to the query chain and access result.Total</pre> After reporting, the validation skill offers to re-run /migrate-transform on just the failed files for a second pass (max 2 rounds). This catches cases where the first pass produced valid but incomplete transformations. <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">8. Full Workflow at a Glance</h2> <pre style="background: rgb(230, 228, 227); color: rgb(30, 41, 59); border-radius: 8px; padding: 0.5rem; overflow-x: auto; margin: 16px 0px; font-family: 'SF Mono', 'Cascadia Code', 'Fira Code', Consolas, 'Courier New', monospace; font-size: 0.85rem; line-height: 1.6;"># 1. Check out a clean branch git checkout -b feature/graph-migration # 2. Run the full migration /migrate-all --project src/MySolution.sln # 3. Make decisions for manual patterns when prompted # 4. Review the migration report # (open .cg-migrations/migrate-all/*-migration-report.md) # 5. Fix any remaining manual items and commit</pre> That is the simplest path. If you need more control, the individual skills (/migrate-scan, /migrate-transform, /migrate-validate) can be run separately and repeated as needed. The decisions file and scan report persist between runs, so you can iterate without losing your choices. <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: 2px solid #e2e8f0;">9. What the Plugin Handles vs. What You Handle</h2> <table style="width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 0.9rem;"> <thead> <tr> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">The plugin handles</th> <th style="background: #1e293b; color: #fff; font-weight: 600; text-align: left; padding: 10px 14px;">You handle</th> </tr> </thead> <tbody> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Finding every S&N API call across the solution</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Reviewing the scan report for completeness</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Tracing wrapper classes and DI dependency chains</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Deciding strategies for manual patterns</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Applying the 17 known API translation rules</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Custom filter/visitor logic that has no Graph equivalent</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Making methods async when execution changes to GetAsync() / GetAsContentAsync()</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Business logic changes (e.g., if UnifiedSearch was used to merge results, you decide how to restructure)</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Adding generic constraints (class, IContentData)</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Integration test updates</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Attributing compiler errors to specific transformation rules</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">Verifying that query results are functionally equivalent</td> </tr> <tr> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">NuGet package additions</td> <td style="padding: 9px 14px; border-bottom: 1px solid #e2e8f0; vertical-align: top;">NuGet package removals (tracked but left for you to confirm)</td> </tr> </tbody> </table> <hr style="border: none; border-top: 1px solid #e2e8f0; margin: 40px 0;" /> <h2 style="font-size: 1.65rem; font-weight: bold; color: #0f172a; margin-top: 56px; margin-bottom: 16px; padding-bottom: 8px; border-bottom: none;">Looking Ahead</h2> The plugin's pattern registry will continue to grow as partners encounter additional S&N patterns during real-world migrations. If you run into a Search & Navigation pattern that the plugin does not handle, the validation report will call it out. File an issue on the GitHub repository at episerver/content-graph-sdk-migrations so the pattern can be added to the registry. <h3>Next Steps</h3> <ol> <li>Install the plugin with /plugin marketplace add episerver/content-graph-sdk-migrations</li> <li>Run /migrate-all on your solution to migrate end-to-end, or start with /migrate-scan to preview the scope first</li> <li>Review the migration report and fix any remaining manual items</li> <li>Read the <a href="/link/5ffa0c0d7b184f049358e62d7fcad94f.aspx">Graph SDK blog post</a> to understand the API you are migrating to</li> </ol> Resources: <ul> <li><a href="/link/5ffa0c0d7b184f049358e62d7fcad94f.aspx">Introducing the Optimizely CMS 13 Graph SDK</a> (the companion blog post covering the Graph SDK API)</li> <li><a href="https://github.com/episerver/content-graph-sdk-migrations">Plugin Repository: episerver/content-graph-sdk-migrations</a></li> </ul> <div style="border-left: 4px solid #16a34a; border-radius: 4px; padding: 16px 20px; margin: 20px 0; font-size: 0.93rem; background: #dcfce7;">Start with the scan Running /migrate-scan is read-only. It does not modify any files. You can run it against any branch at any time to understand the scope of the migration before committing to the transformation. </div> This guide is based on the cg-migrate Claude Code plugin for migrating Search & Navigation to the Optimizely Graph SDK. The plugin is actively maintained and the pattern registry grows with each release.2026-06-24T17:58:56.0000000Z

Blog post