Partial Routers

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

Average rating: 0 No reviews

Outline

At a glance

SEO Extension: Maps URL segments to non-page data like external databases or the Dynamic Data Store (DDS).
Core Interface: Uses IPartialRouter to resolve incoming requests and generate outgoing virtual paths for dynamic content.
State Management: Leverages IHttpContextAccessor to pass routed data to controllers, bypassing immutable route values in CMS 12.
Performance: Requires robust caching and segment validation to maintain site speed and prevent routing loops.

In complex enterprise architectures, content often exists outside the standard CMS page tree. Optimizely CMS 12 provides Partial Routing as a robust mechanism to map specific URL segments to dynamic data sources, such as external databases, product catalogs, or the Dynamic Data Store (DDS). This method enables the creation of search-engine-friendly (SEO) URLs for non-page content while maintaining the context of a "parent" CMS page.

1. Technical Purpose and Use Cases

Standard routing in Optimizely resolves URLs by matching segments to the IContent hierarchy. Partial routing extends this logic by allowing a "pointing" content item (often a page) to handle the remaining segments of a URL manually.

Dynamic External Data: Routing to news articles, blog entries, or product details stored in an external SQL database or DDS.
Hierarchical Dynamic Routing: Managing complex URL structures like /news/category/article-name/ where /news/ is a CMS page and the rest is dynamic.
Pagination and Filtering: Handling segments purely for data filtering without creating physical child pages.

2. The IPartialRouter<TContent, TRoutedData> Interface

The core of partial routing is the implementation of the IPartialRouter interface, found in the EPiServer.Core.Routing namespace. This interface uses two generic types:

TContent: The type of content in the CMS tree that acts as the routing anchor (e.g., NewsContainerPage).
TRoutedData: The type of non-page data to which the URL will be resolved (e.g., a NewsContent object).

Core Interface Methods

RoutePartial: Invoked during incoming request resolution. It parses the segments following the resolved TContent and determines which TRoutedData instance matches them.
GetPartialVirtualPath: Invoked during outgoing URL generation. It constructs a "friendly URL" based on a TRoutedData instance and its associated TContent anchor.

3. Implementation Patterns for CMS 12

In CMS 12 (.NET 6/8), partial routing integrates with the underlying ASP.NET Core routing system. A critical change from legacy versions is the immutability of UrlResolverContext.RouteValues.

Resolving Data in RoutePartial

The implementation must use the SegmentContext to read URL segments and update the state to indicate how much of the URL was consumed.

public object RoutePartial(NewsContainer content, UrlResolverContext urlResolverContext)
{
    // Retrieve the next segment (e.g., 'sports')
    var categorySegment = urlResolverContext.GetNextSegment();
    if (string.IsNullOrEmpty(categorySegment.Next))
    {
        return null;
    }

    // Retrieve the article segment (e.g., 'local-match')
    var articleSegment = urlResolverContext.GetNextSegment(categorySegment.Remaining);
    
    // Logic to fetch content from an external store
    var newsItem = _newsStore.GetArticle(categorySegment.Next, articleSegment.Next);

    if (newsItem != null)
    {
        // Mark the segments as handled by setting the remaining path
        urlResolverContext.RemainingSegments = articleSegment.Remaining;
        return newsItem;
    }

    return null;
}

Passing Data to Controllers

Since RouteValues cannot be directly modified in the context, developers must use the IHttpContextAccessor to store additional parameters (like IDs or flags) that the target controller might need.

// Inside RoutePartial
_httpContextAccessor.HttpContext.Items["RoutedNewsItem"] = newsItem;

The corresponding controller can then retrieve this data:

public IActionResult Index(NewsContainer currentContent)
{
    var newsItem = _httpContextAccessor.HttpContext.Items["RoutedNewsItem"] as NewsContent;
    return View(new NewsViewModel(currentContent, newsItem));
}

4. System Registration

Registration in CMS 12 is handled through the Dependency Injection container. This is typically implemented within the Startup.cs ConfigureServices method or a dedicated IServiceCollection extension.

public void ConfigureServices(IServiceCollection services)
{
    // Register the router implementation
    services.AddSingleton<IPartialRouter, MyCustomPartialRouter>();
}

5. Generating Outgoing URLs

To ensure that links to dynamic content are SEO-friendly, the GetPartialVirtualPath method must be correctly implemented. This allows standard CMS helper methods (like Url.ContentUrl) to generate accurate paths for dynamic objects.

public PartialRouteValues GetPartialVirtualPath(NewsContent content, UrlGeneratorContext urlGeneratorContext)
{
    return new PartialRouteValues
    {
        // Reference to the CMS anchor page
        BaseContentLink = _options.NewsContainerRoot,
        // The dynamic segments to append to the anchor URL
        PartialPath = $"{content.Category}/{content.UrlSegment}"
    };
}

6. Performance and Best Practices

Caching: Partial routers are executed frequently. Ensure that the lookup logic (e.g., database queries) is backed by a robust caching strategy using IContentCacheKey or ISignaledCache.
GUID Consistency: When routing to content that implements IContent (but is not in the tree), ensure it has a stable, unique GUID to support routing and features like Optimizely Graph.
Segment Management: Always check for null or empty segments to avoid infinite routing loops or unnecessary database hits for malformed URLs.

Conclusion

Partial Routers provide a sophisticated method for merging external and dynamic data into the standard Optimizely CMS URL structure. By leveraging IPartialRouter and modern .NET DI, developers can create highly scalable, performant, and SEO-optimized navigation systems that exist beyond the traditional content tree boundaries.