Initialize the C# SDK

30 min

Use the builder to initialize the C# SDK and instantiate an instance of the Optimizely Feature Experimentation client class that exposes API methods like the Decide methods.

Version

4.0.0

Description

The constructor accepts a configuration object to configure Optimizely.

The SDK provides a default implementation, but you may want to override the optional parameters for your production environments. For example, you can override these to configure an error handler and logger to catch issues, an event dispatcher to manage network calls, and a User Profile Service to ensure sticky bucketing.

Parameters

The following are the required and optional parameters for initializing the C# SDK:

Parameter	Type	Description
`datafile` _optional_	String	The JSON string representing the project.
`configManager` _optional_	`ProjectConfigManager`	The project config manager provides the project config to the client.
`eventDispatcher` _optional_	`IEventDispatcher`	An event handler to manage network calls.
`logger` _optional_	`ILogger`	A logger implementation to log issues.
`errorHandler` _optional_	`IErrorHandler`	An error handler object to handle errors.
`userProfileService` _optional_	`UserProfileService`	A user profile service.
`skipJsonValidation` _optional_	Boolean	Specifies whether the JSON should be validated. Set to `true` to skip JSON validation on the schema, or `false` to perform validation.
`datafileAccessToken` _optional_	String	Use an access token (with an `sdkKey`) to fetch the datafile from an authenticated endpoint. Find your datafile access token in the Optimizely app at Settings > Environments. Select your secure environment, and copy the Datafile access token. See the [Use authenticated datafile in a secure environment](#use-authenticated-datafile-in-a-secure-environment) section.
`defaultDecideOptions` _optional_	Array	Array of OptimizelyDecideOption enums. This parameter sets the default decide options applied to all the Decide calls made during the lifetime of the Optimizely client. Additionally, you can pass options to individual Decide methods (does not override defaults). For details on `decide` options, see [OptimizelyDecideOption](https://docs.developers.optimizely.com/feature-experimentation/docs/decide-methods-csharp#optimizelydecideoption).
`withOdpManager(OdpManager)`		`OdpManager` contains the logic supporting Real-Time Audiences for Feature Experimentation-related features, including audiences. By default, the C# SDK enables the Real-Time Audiences for Feature Experimentation methods. But, the methods do nothing unless you have enabled and configured [Real-Time Audiences for Feature Experimentation](https://docs.developers.optimizely.com/feature-experimentation/docs/real-time-audiences-for-feature-experimentation). To optionally disable Real-Time Audiences completely, see [OdpManager](https://docs.developers.optimizely.com/feature-experimentation/docs/initialize-sdk-csharp#odpmanager).

Returns

Instantiates an instance of the Optimizely class.

Automatic datafile management (ADM)

Optimizely provides out-of-the-box functionality to dynamically manage datafiles (configuration files) on either the client or the server. The C# SDK provides default implementations of an Optimizely ProjectConfigManager. The package also includes a factory class, OptimizelyFactory, which you can use to instantiate the SDK with the default configuration of HttpProjectConfigManager.

Whenever the experiment configuration changes, the SDK uses automatic datafile management (ADM) to handle the change for you. In the C# SDK, you can provide a sdkKey or datafile or both.

When initializing with just the SDK key – The SDK polls for datafile changes in the background at regular intervals.

When initializing with just the datafile – The SDK does not poll for datafile changes in the background.

When initializing with both the SDK key and datafile – The SDK uses the given datafile and start polling for datafile changes in the background.

Basic example

The following code example shows basic C# usage.

using OptimizelySDK;

public class Program
{
    public static void Main(string[] args)
    {
       var sdkKey = args[0];
     	 var optimizely = OptimizelyFactory.NewDefaultInstance(sdkKey);
    }
}

Advanced examples

When you configure a logger, you should pass it into the ProjectConfigManager instance as well.

In the C# SDK, you only need to pass the SDK key value to instantiate a client. Whenever the experiment configuration changes, the SDK handles the change for you.

Include sdkKey as a string property in the options object you pass to the CreateInstance method.

When you provide the sdkKey, the SDK instance downloads the datafile associated with that sdkKey. When the download completes, the SDK instance updates itself to use the downloaded datafile.

Pass all components (Logger, ErrorHandler, NotificationCenter) to the Optimizely constructor. Not passing a component fails to enable its respective functionality. In other words, components only work when passed to the constructor.

// Initialize with SDK key and default configuration
const string sdkKey = "YOUR_SDK_KEY"; // replace with your SDK Key
var optimizely = OptimizelyFactory.NewDefaultInstance(sdkKey);

// You can also customize the SDK instance with custom configuration. 
// In this example you are customizing the project config manager to poll every 5 minutes for the datafile.
var projectConfigManager = new HttpProjectConfigManager.Builder()
  .WithSdkKey(sdkKey)
  .WithPollingInterval(TimeSpan.FromMinutes(5))
  // .WithLogger(logger) // needed if you are configuring a logger
  // .WithErrorHandler(errorHandler) // needed if you are configuring an error handler
  // .WithNotificationCenter(notificationCenter) // needed if you are subscribing config update
  .Build();

optimizely = new Optimizely(projectConfigManager);

// Initialize with Logger
optimizely = new Optimizely(projectConfigManager, logger: logger);

// Initialize with Logger, ErrorHandler
optimizely = new Optimizely(projectConfigManager, errorHandler: errorHandler, logger: logger);

// Initialize with NotificationCenter, Logger, ErrorHandler
optimizely = new Optimizely(projectConfigManager, notificationCenter: notificationCenter, errorHandler: errorHandler, logger: logger);

// Note: Use OptimizelyFactory NewDefaultInstance method to use same logger, errorHandler and notificationCenter for all of its 
//   Components (Optimizely, EventProcessor, HttpProjectConfigManager)

The following is a code example showing advanced configuration for C# ADM. The following sections describe advanced configuration properties. This advanced example shows how to construct the individual components directly to override various configurations. This gives you full control over which implementations to use and how to use them.

using OptimizelySDK;
using OptimizelySDK.Config;

public class Program
{
    public static void Main(string[] args)
    {
      var sdkKey = args[0];
      
      // You can also use your own implementation of the ProjectConfigManager interface
      var projectConfigManager = new HttpProjectConfigManager.Builder()
        .WithSdkKey(sdkKey)
        .WithPollingInterval(TimeSpan.FromMinutes(1))
        .Build();

      var optimizely = new Optimizely(projectConfigManager);
    }
}

HttpProjectConfigManager

HttpProjectConfigManager is an implementation of the abstract PollingProjectConfigManager. The Poll method is extended and makes an HTTP GET request to the configured URL to asynchronously download the project datafile and initialize an instance of the ProjectConfig.

By default, HttpProjectConfigManager blocks until the first successful datafile retrieval, up to a configurable timeout. Set the frequency of the polling method and the blocking timeout with HttpProjectConfigManager.Builder.

var projectConfigManager = new HttpProjectConfigManager.Builder()
  .WithSdkKey(sdkKey)
  .WithPollingInterval(TimeSpan.FromMinutes(1))
  .Build();

SDK key

The SDK key composes the outbound HTTP request to the default datafile location on the Optimizely CDN.

Poll interval

The polling interval specifies a fixed delay between consecutive HTTP requests for the datafile, using any range supported by Timespan.

Initial datafile

You can provide an initial datafile through the builder to bootstrap the ProjectConfigManager, allowing you to use it immediately without blocking execution. The initial datafile is also a fallback datafile if an HTTP connection cannot be established. This is useful in mobile environments, where internet connectivity is not guaranteed.

The SDK discards the initial datafile after the first successful datafile poll.

Builder methods

Use the following builder methods to customize the HttpProjectConfigManager configuration:

Property	Default value	Description
WithDatafile(string)	null	Initial datafile, typically sourced from a local cached source
WithUrl(string)	null	URL override location used to specify custom HTTP source for the Optimizely datafile
WithFormat(string)	null	Parameterized datafile URL by SDK key
WithPollingInterval(TimeSpan)	5 minutes	Fixed delay between fetches for the datafile
WithBlockingTimeoutPeriod(TimeSpan)	15 seconds	Maximum time to wait for initial bootstrapping. The valid timeout duration is 1 to 4294967294 milliseconds.
WithSdkKey(string)	null	Optimizely project SDK key; required unless source URL is overridden

Update config notifications

The SDK triggers a notification signal after fetching a new datafile. To subscribe to these notifications, use the NotificationCenter.AddNotification() method.

optimizely.NotificationCenter.AddNotification(
    NotificationCenter.NotificationType.OptimizelyConfigUpdate,
    () => Console.WriteLine("Received new datafile configuration"));

You must first configure Real-Time Audiences for Feature Experimentation to use odpManager. Then, you must configure this parameter in the SDK to use Real-Time Audiences.

// Continuing from above.

var yourCustomEventQueue = new BlockingCollection<object>(Constants.DEFAULT_QUEUE_CAPACITY);

var eventManager = new OdpEventManager.Builder()
    .WithEventQueue(yourCustomEventQueue)
    .WithOdpEventApiManager(eventApiManager)
    .WithFlushInterval(TimeSpan.FromMinutes(3))
    .WithTimeoutInterval(TimeSpan.FromSeconds(5))
    .WithAutoStart(true)
    .WithLogger(logger)
    .WithErrorHandler(errorHandler)
    .Build();

OptimizelyFactory

OptimizelyFactory provides a basic utility to instantiate the Optimizely SDK with minimal configuration options.

OptimizelyFactory does not capture all configuration and initialization options. For more use cases, build the resources with their constructors.

You must provide the SDK key at runtime directly using the factory method:

var optimizely = OptimizelyFactory.NewDefaultInstance("YOUR_SDK_KEY");

Instantiate using datafile

You can also instantiate with a hard-coded datafile. If you do not pass in an SDK key, the Optimizely Client does not automatically sync newer datafile versions. Any time you retrieve an updated datafile, just re-instantiate the same client.

To instantiate a client for simple applications, provide a datafile specifying the project configuration for a given environment. For most advanced implementations, you should customize the logger or error handler for your specific requirements.

using OptimizelySDK;

// Instantiate an Optimizely client
var datafile = "YOUR_DATAFILE_JSON_STRING";
var optimizely = new Optimizely(datafile);

Use authenticated datafile in a secure environment

You can fetch the datafile from an authenticated endpoint using a server-side (only) Optimizely SDK, like the C# SDK.

To use an authenticated datafile, download your environment's access token from the Optimizely app by going to Settings > Environments. Select your secure environment, and copy the Datafile access token. The following example shows how to initialize the Optimizely client using an access token and sdkKey, enabling the client to fetch the authenticated datafile and complete initialization.

// fetch the datafile from an authenticated endpoint
var datafileAccessToken = "YOUR_DATAFILE_ACCESS_TOKEN";
var sdkKey = "YOUR_SDK_KEY";

var optimizely = OptimizelyFactory.NewDefaultInstance(sdkKey, null, datafileAccessToken);

Dispose of the client

For effective resource management with the Optimizely C# SDK, you must properly close the Optimizely client instance when it is no longer needed. This is done by calling optimizely.Dispose().

The .Dispose() method ensures that the processes and queues associated with the instance are properly released. This is essential for preventing memory leaks and ensuring that the application runs efficiently, especially in environments where resources are limited or in applications that create and dispose of many instances over their lifecycle.

See Dispose the C# SDK on application exit.

OdpManager

OdpManager contains the logic supporting Real-Time Audiences for Feature Experimentation.

You must use .NET Framework version 4.5+ or Standard 2.0+ to use Real-Time Audiences for Feature Experimentation.

By default, the C# SDK enables the Real-Time Audiences for Feature Experimentation methods. But, the methods do nothing unless you have enabled and configured Real-Time Audiences for Feature Experimentation.

If necessary, to disable Real-Time Audiences for Feature Experimentation altogether, create a new OdpManager.Builder().Build(asEnabled: false) and pass it when instantiating a new Optimizely() instance.

The following settings are configurable when the C# SDK is initialized:

ODP SegmentsCache size – cacheSize

Default – 10,000

Set to 0 to disable caching.

ODP SegmentsCache timeout (in seconds) – itemTimeout

Default – 600 secs (10 minutes)

Set to 0 to disable timeout (never expires).

ODP enable – asEnabled

Default – true (enabled)

The C# SDK returns or logs an odpNotEnabled error when ODP is disabled and its features are requested.

See Customize OdpEventManager.

OdpSegmentManager

This module provides an interface to the remote Optimizely Data Platform (ODP) server for audience mappings.

It fetches qualified audiences for the given user context and returns them as a string array in the completion handler.

It also manages a segment's cache shared for all user contexts. The cache is in memory (not persistent), and a device reboot or app termination resets it.

OdpEventManager

This module provides an interface to the remote ODP server for events.

It queues pending events (persistent) and sends them (in batches of up to 10) to the ODP server when resources are available, including network connection and ODP public key (in the SDK's datafile).

The C# SDK tries to dispatch all events (stored in a persistent queue and retried on recoverable errors) but does not guarantee completion.

using OptimizelySDK.ErrorHandler;
using OptimizelySDK.Logger;
using OptimizelySDK.Odp;

var logger = new DefaultLogger();
var errorHandler = new DefaultErrorHandler();
var httpClient = new HttpClient(); // or your own implementation of HttpClient

var segmentApiManager = new OdpSegmentApiManager(logger, errorHandler, httpClient);
var segmentManager = new OdpSegmentManager(
    segmentApiManager,
    cacheSize: 10_000, // default is 10_000
    itemTimeout: TimeSpan.FromMinutes(10), // default is 10 minutes
    logger);

var eventManager = new OdpEventManager.Builder().WithLogger(logger)
    .WithErrorHandler(errorHandler)
 		// Optional. Optimizely suggest a BlockingCollection or your own thread-safe collection
 		// .WithEventQueue(new BlockingCollection<object>(10_000))
 		// Optional. If you choose to control the httpClient, you must also implement your own 
		// .WithOdpEventApiManager(new OdpEventApiManager(logger, errorHandler, httpClient))
    .Build();

var odpManager = new OdpManager.Builder()
    .WithSegmentManager(segmentManager)
    .WithEventManager(eventManager)
    .WithLogger(logger)
    .WithErrorHandler(errorHandler)
    .Build();

Customize OdpSegmentApiManager

When provided, OdpSegmentApiManager enables customization.

using OptimizelySDK.ErrorHandler;
using OptimizelySDK.Logger;
using OptimizelySDK.Odp;

var logger = new DefaultLogger();
var errorHandler = new DefaultErrorHandler();
var yourCustomHttpClient = new HttpClient();

var segmentApiManager = new OdpSegmentApiManager(logger, errorHandler, yourCustomHttpClient);

Customize OdpSegmentManager

You can provide your customized OdpSegmentApiManager to the OdpSegmentManager along with different values for cache size and item timeouts.

// Continuing from above.

var segmentManager = new OdpSegmentManager(
    apiManager: segmentApiManager,
    cacheSize: Constants.DEFAULT_MAX_CACHE_SIZE,
    itemTimeout: TimeSpan.FromSeconds(Constants.DEFAULT_CACHE_SECONDS),
    logger: logger);

Custom cache

You can use a custom caching mechanism for the OdpSegmentManager to store the FetchQualifiedSegments results. You must implement the ICache interface or use LruCache to provide a custom cache.

// Continuing from above.

var segmentApiManager = new OdpSegmentApiManager(logger, errorHandler, yourCustomHttpClient);
var yourCustomSegmentCache = new LruCache<List<string>>();

var segmentManager = new OdpSegmentManager(
    apiManager: segmentApiManager, 
    cache: yourCustomSegmentCache, 
    logger: logger);

Customize OdpEventApiManager

When created, OdpEventApiManager enables customization.

// Continuing from above.

var eventApiManager = new OdpEventApiManager(logger, errorHandler, yourCustomHttpClient);

Customize OdpEventManager

You can provide your customized Event API Manager to the OdpEventManager and adjust the flush interval, timeout interval, and auto-starting queue processing.

// Continuing from above.

var yourCustomEventQueue = new BlockingCollection<object>(Constants.DEFAULT_QUEUE_CAPACITY);

var eventManager = new OdpEventManager.Builder()
    .WithEventQueue(yourCustomEventQueue)
    .WithOdpEventApiManager(eventApiManager)
    .WithFlushInterval(TimeSpan.FromMinutes(3))
    .WithTimeoutInterval(TimeSpan.FromSeconds(5))
    .WithAutoStart(true)
    .WithLogger(logger)
    .WithErrorHandler(errorHandler)
    .Build();

CMAB Configuration

Configure Contextual Multi-Armed Bandit (CMAB) settings at initialization time, including caching behavior and prediction endpoint customization.

Pass a CmabConfig object to SetCmabConfig on the OptimizelyFactory when initializing your client:

Parameters

Parameter	Type	Default	Description
CacheSize	int?	10,000	Maximum number of cached decisions.
CacheTtl	TimeSpan?	30 minutes	Time-to-live for cache entries.
Cache	ICacheWithRemove<CmabCacheEntry>	LruCache<CmabCacheEntry>	Optional custom cache implementation for distributed deployments. When provided, CacheSize and CacheTtl are ignored.
PredictionEndpointTemplate	string	https://prediction.cmab.optimizely.com/predict/\{0}	Custom prediction endpoint template. Use as placeholder for rule ID. Useful for proxy configurations or custom routing.

When CacheSize or CacheTtl are set to null, the SDK uses the default values shown above. If a custom Cache is provided, it takes precedence over CacheSize and CacheTtl.

Source files

The language and platform source files containing the implementation for C# are available on GitHub.