---
title: Overview of Graph C# SDK
slug: cms-13/docs/overview-of-c-sharp-sdk
docTags: 
createdAt: 2026-07-30T20:22:02.544Z
---

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](docId:1bX4s5MQJssocEnQERGi7). 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.

```csharp
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](docId\:kbDWyxx7zIiD7zR2pAUXt)     | Install, configure, and run your first query                       |
| [Authentication](docId:7S9dTMUKYWTDBF6Vs0grs)   | Single Key versus Basic authentication and security best practices |
| [Search tracking](docId\:wzB3gTVamNCXBp17QrLo5) | 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](docId\:f0IXlPPYtzSZ9ySIUEu6K)       | Filter by string, numeric, boolean, and date values, and combine them with AND or OR logic. |
| [Ordering](docId\:RqjUSa_Yz8PzEglRAQGPJ)        | Apply `OrderBy` and `ThenBy` for ascending or descending sorts.                             |
| [Searching](docId\:wkIAHH2c8t0jVgJpquxTS)       | Run full-text search, field-specific search, and relevance boosting.                        |
| [Pagination](docId\:W3aOzwcLJHZ_-OYEdo1M6)      | Implement `Skip` and `Limit` for large result sets.                                         |
| [Include total](docId\:o5_jhMAfvFVRhR6IDGo-n)   | Return the total result count for page navigation.                                          |
| [Aggregations](docId:_B9t8PFTxIhFThrub7yqk)     | Use facets and counts for category filtering.                                               |
| [Decay functions](docId\:EWPWIBcTlg2hl0w9t3duo) | Apply recency-based relevance scoring.                                                      |
| [Synonyms](docId\:AACVYxCccZSs9YIeEtTT2)        | Apply synonym expansion through slot-based filters.                                         |
| [Pinned results](docId\:mt_i6G7eyJrZzplLV3xUr)  | 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:

```csharp
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](docId\:j-pEGPZklByCTm-Dwmvwe).