Overview of Graph C# SDK

7 min

The Graph C# SDK provides a strongly typed, LINQ-style API for querying content from Optimizely Graph in .NET applications. Instead of writing raw GraphQL queries, chain C# methods to filter, search, sort, paginate, and shape results.

For foundational concepts and platform capabilities, see the Optimizely Graph documentation. That resource covers indexing, schema design, and search architecture. To migrate from Search & Navigation to Optimizely Graph, review the migration guides for feature mapping and best practices.

Example query

This example demonstrates how a single query chains filtering, searching, sorting, and pagination. It searches BlogPostPage content for optimizely, filters by the Tutorials category, and sorts by publish date descending. The query returns the first 10 results and includes the total match count.

var result = await _graphClient
    .QueryContent<BlogPostPage>()
    .SearchFor("optimizely")
    .UsingFullText()
    .Where(x => x.BlogCategory == "Tutorials")
    .OrderBy(x => x.StartPublish, OrderDirection.Descending)
    .Skip(0)
    .Limit(10)
    .IncludeTotal()
    .GetAsContentAsync();

NuGet packages

Install the following NuGet packages to enable the C# SDK.

Package	Purpose
Optimizely.Graph.Cms.Query	Provides the core Graph C# query API to retrieve content from Optimizely Graph.
Optimizely.Graph.AspNetCore	Adds ASP.NET Core integrations for search tracking and click-through analytics.

Guides for the C# SDK

The following guides explain how to use the C# SDK:

Guide	What it covers
Quick start	Install, configure, and run your first query
Authentication	Single Key versus Basic authentication and security best practices
Search tracking	Track which results users click, Beacon API integration

Query patterns

Each pattern guide demonstrates a specific query operation with code examples and usage scenarios.

Pattern guide	What it covers
Filtering	Filter by string, numeric, boolean, and date values, and combine them with AND or OR logic.
Ordering	Apply OrderBy and ThenBy for ascending or descending sorts.
Searching	Run full-text search, field-specific search, and relevance boosting.
Pagination	Implement Skip and Limit for large result sets.
Include total	Return the total result count for page navigation.
Aggregations	Use facets and counts for category filtering.
Decay functions	Apply recency-based relevance scoring.
Synonyms	Apply synonym expansion through slot-based filters.
Pinned results	Promote specific items to the top of search results.

Configure field mappings

The Graph C# SDK maps each content type property to a field name in the Optimizely Graph schema. The SDK includes default mappings for common CMS types. Content types that inherit from a mapped type, or implement a mapped interface, reuse its mappings.

Configure a custom mapping when a property name does not match its Graph field name. In CMS 13.1.1 and later, you can configure mappings in startup code. IntelliSense lists the available properties, and the compiler checks the property names.

Pass a configuration action to AddGraphContentClient, and call ConfigureType<T> for each content type that you want to map:

services.AddGraphContentClient(options =>
{
    options.ConfigureType<ArticlePage>()
        .ConfigureField(x => x.Author, "authorName", IndexingType.Queryable)
        .ObjectGraphName("ArticlePage");
});

Chain the following methods after ConfigureType<T>:

ConfigureField – Maps a property to a Graph field name. The optional third parameter sets the indexing type. If you omit it, the SDK uses the indexing type from the [IndexingType] attribute or the Admin UI. For a computed field, the SDK uses the indexing type from IncludeField. Otherwise, the SDK uses IndexingType.Default.

ObjectGraphName – Sets the type name in the Graph schema.

You can also define field mappings in appsettings.json. When both sources map the same property, the startup code mapping takes priority.

Reference

For HTTP error codes, causes, and fixes, see the Error reference.