From ddc42b88f2259d636e9be87ff4e6acdb7eee29a0 Mon Sep 17 00:00:00 2001 From: esrakartalOpt Date: Tue, 24 Feb 2026 13:11:34 -0600 Subject: [PATCH] [FSSDK-12222] [C#] Docs Bash - README update --- README.md | 409 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 263 insertions(+), 146 deletions(-) diff --git a/README.md b/README.md index 9d21c7e4..5a2431b9 100644 --- a/README.md +++ b/README.md @@ -1,220 +1,338 @@ # Optimizely C# SDK + ![Semantic](https://img.shields.io/badge/sem-ver-lightgrey.svg?style=plastic) ![CI](https://github.com/optimizely/csharp-sdk/actions/workflows/csharp.yml/badge.svg?branch=master) [![NuGet](https://img.shields.io/nuget/v/Optimizely.SDK.svg?style=plastic)](https://www.nuget.org/packages/Optimizely.SDK/) [![Apache 2.0](https://img.shields.io/github/license/nebula-plugins/gradle-extra-configurations-plugin.svg)](http://www.apache.org/licenses/LICENSE-2.0) -This repository houses the .Net based C# SDK for use with Optimizely Feature Experimentation and Optimizely Full Stack (legacy). +This is the official C# SDK for use with Optimizely Feature Experimentation and Optimizely Full Stack (legacy). -Optimizely Feature Experimentation is an A/B testing and feature management tool for product development teams, letting you experiment at every step. Using Optimizely Feature Experimentation allows for every feature on your roadmap to be an opportunity to discover hidden insights. Learn more at [Optimizely.com](https://www.optimizely.com/products/experiment/feature-experimentation/), or see the [developer documentation](https://docs.developers.optimizely.com/experimentation/v4.0.0-full-stack/docs/welcome). +Optimizely Feature Experimentation is an A/B testing and feature management tool for product development teams that enables you to experiment at every step. Using Optimizely Feature Experimentation allows for every feature on your roadmap to be an opportunity to discover hidden insights. Learn more at [Optimizely.com](https://www.optimizely.com/products/experiment/feature-experimentation/), or see the [developer documentation](https://docs.developers.optimizely.com/experimentation/v4.0.0-full-stack/docs/welcome). Optimizely Rollouts is [free feature flags](https://www.optimizely.com/free-feature-flagging/) for development teams. You can easily roll out and roll back features in any application without code deploys, mitigating risk for every feature on your roadmap. +--- ## Get Started -Refer to the [C# SDK's developer documentation](https://docs.developers.optimizely.com/experimentation/v4.0.0-full-stack/docs/csharp-sdk) for detailed instructions on getting started with using the SDK. +> Refer to the [C# SDK's developer documentation](https://docs.developers.optimizely.com/experimentation/v4.0.0-full-stack/docs/csharp-sdk) for detailed instructions on getting started with using the SDK. + +### Prerequisites + +Ensure the SDK supports the .NET platforms you're targeting. We officially support: + +- **.NET Framework**: 4.0, 4.5+ +- **.NET Standard**: 2.0+ +- **.NET Core**: 2.0+ +- **.NET**: 5.0+ + +> **Note**: .NET Framework 3.5 and .NET Standard 1.6 are deprecated as of SDK version 4.0.0. -### Install the C# SDK +> **Feature Availability**: ODP (Optimizely Data Platform) and CMAB (Contextual Multi-Armed Bandit) features require .NET Framework 4.5+ or .NET Standard 2.0+. -The SDK can be installed through [NuGet](https://www.nuget.org): +### Install the SDK +Install via [NuGet](https://www.nuget.org/packages/Optimizely.SDK/): + +**Package Manager Console:** ``` PM> Install-Package Optimizely.SDK ``` -An ASP.Net MVC sample project demonstrating how to use the SDK is available as well: +**.NET CLI:** +```sh +dotnet add package Optimizely.SDK +``` + +**PackageReference:** +```xml + +``` +An ASP.NET MVC sample project is also available: ``` PM> Install-Package Optimizely.SDK.Sample ``` -Simply compile and run the Sample application to see it in use. -Note that the way the Demo App stores data in memory is not recommended for production use -and is merely illustrates how to use the SDK. - - ### Feature Management Access To access the Feature Management configuration in the Optimizely dashboard, please contact your Optimizely customer success manager. ## Use the C# SDK -See the Optimizely Feature Experimentation [developer documentation](https://docs.developers.optimizely.com/experimentation/v4.0-full-stack/docs/csharp-sdk) to learn how to set up your first C# project and use the SDK. +See the [developer documentation](https://docs.developers.optimizely.com/experimentation/v4.0-full-stack/docs/csharp-sdk) to learn how to set up your first C# project and use the SDK. ### Initialization -Create the Optimizely Client, for example: +Initialize the SDK using `OptimizelyFactory`: -``` -private static Optimizely Optimizely = - new Optimizely( - datafile: myProjectConfig, - eventDispatcher: myEventDispatcher, - logger: myLogger, - errorHandler: myErrorHandler, - skipJsonValidation: false); +```csharp +using OptimizelySDK; + +// Initialize with SDK key - automatically polls for datafile updates +var optimizely = OptimizelyFactory.NewDefaultInstance("YOUR_SDK_KEY"); ``` -Since this class parses the Project Config file, you should not create this per request. +For advanced initialization with custom components: -#### APIs +```csharp +using OptimizelySDK.Config; +using OptimizelySDK.Event; -This class exposes three main calls: -1. Activate -2. Track -3. GetVariation +var httpConfigManager = new HttpProjectConfigManager.Builder() + .WithSdkKey("YOUR_SDK_KEY") + .WithPollingInterval(TimeSpan.FromMinutes(5)) + .Build(); -Activate and Track are used in the demonstration app. See the Optimizely documentation regarding how to use these. +var batchEventProcessor = new BatchEventProcessor.Builder() + .WithMaxBatchSize(10) + .WithFlushInterval(TimeSpan.FromSeconds(30)) + .Build(); -#### Plug-in Interfaces +var optimizely = new Optimizely( + configManager: httpConfigManager, + eventProcessor: batchEventProcessor +); +``` -The Optimizely client object accepts the following plug-ins: -1. `IEventDispatcher` handles the HTTP requests to Optimizely. The default implementation is an asynchronous "fire and forget". -2. `ILogger` exposes a single method, Log, to record activity in the SDK. An example of a class to bridge the SDK's Log to Log4Net is provided in the Demo Application. -3. `IErrorHandler` allows you to implement custom logic when Exceptions are thrown. Note that Exception information is already included in the Log. -4. `ProjectConfigManager` exposes method for retrieving ProjectConfig instance. Examples include `FallbackProjectConfigManager` and `HttpProjectConfigManager`. -5. `EventProcessor` provides an intermediary processing stage within event production. It's assumed that the EventProcessor dispatches events via a provided EventDispatcher. Examples include `ForwardingEventProcessor` and `BatchEventProcessor`. -These are optional plug-ins and default behavior is implement if none are provided. +### Making Decisions -#### OptimizelyFactory +Use the **User Context** and **Decide** methods for feature flag decisions: -[`OptimizelyFactory`](https://github.com/optimizely/csharp-sdk/blob/master/OptimizelySDK/OptimizelyFactory.cs) -provides basic utility to instantiate the Optimizely SDK with a minimal number of configuration options. +```csharp +// Create a user context +var user = optimizely.CreateUserContext("user123", new UserAttributes +{ + { "country", "US" }, + { "subscription_tier", "premium" } +}); -`OptimizelyFactory` does not capture all configuration and initialization options. For more use cases, -build the resources via their respective builder classes. +// Make a decision +var decision = user.Decide("feature_flag_key"); -##### Use OptimizelyFactory +if (decision.Enabled) +{ + var theme = decision.Variables.ToDictionary()["theme"].ToString(); + Console.WriteLine($"Feature enabled with theme: {theme}"); +} -You must provide the SDK key at runtime, either directly via the factory method: -``` -Optimizely optimizely = OptimizelyFactory.newDefaultInstance(<>); -``` +// Decide for multiple flags +var decisions = user.DecideForKeys(new[] { "flag1", "flag2", "flag3" }); -You can also provide default datafile with the SDK key. -``` -Optimizely optimizely = OptimizelyFactory.newDefaultInstance(<>, <>); +// Decide for all flags +var allDecisions = user.DecideAll(); ``` -##### Using App.config in OptimizelyFactory -OptimizelyFactory provides support of setting configuration variables in App.config: -User can provide variables using following procedure: -1. In App.config file of your project in **** add following: -``` - -
- -``` -2. Now add **optlySDKConfigSection** below ****. In this section you can add and set following **HttpProjectConfigManager** and **BatchEventProcessor** variables: -``` - - - - - - - - - -``` -3. After setting these variables you can instantiate the Optimizely SDK using function: -``` -Optimizely optimizely = OptimizelyFactory.newDefaultInstance(); +#### Decide Options + +Customize decision behavior: + +```csharp +var decision = user.Decide("feature_key", new[] +{ + OptimizelyDecideOption.DISABLE_DECISION_EVENT, + OptimizelyDecideOption.INCLUDE_REASONS +}); ``` -#### BatchEventProcessor -[BatchEventProcessor](https://github.com/optimizely/csharp-sdk/blob/master/OptimizelySDK/Event/BatchEventProcessor.cs) is a batched implementation of the [EventProcessor](https://github.com/optimizely/csharp-sdk/blob/master/OptimizelySDK/Event/EventProcessor.cs) - * Events passed to the BatchEventProcessor are immediately added to a BlockingQueue. - * The BatchEventProcessor maintains a single consumer thread that pulls events off of the BlockingQueue and buffers them for either a configured batch size or for a maximum duration before the resulting LogEvent is sent to the NotificationManager. -##### Use BatchEventProcessor +**Available Options:** +- `DISABLE_DECISION_EVENT` - Don't send impression events +- `ENABLED_FLAGS_ONLY` - Return only enabled flags +- `IGNORE_USER_PROFILE_SERVICE` - Skip user profile service +- `INCLUDE_REASONS` - Include decision reasons for debugging +- `EXCLUDE_VARIABLES` - Exclude feature variables +- `IGNORE_CMAB_CACHE` - Bypass CMAB cache (CMAB only) +- `RESET_CMAB_CACHE` - Clear CMAB cache (CMAB only) +- `INVALIDATE_USER_CMAB_CACHE` - Invalidate user-specific CMAB cache (CMAB only) +### CMAB (Contextual Multi-Armed Bandit) + +> Available in SDK 4.2.0+ for .NET Framework 4.5+ and .NET Standard 2.0+ + +Configure CMAB for dynamic variation optimization: + +```csharp +var cmabConfig = new CmabConfig() + .SetCacheSize(1000) + .SetCacheTtl(TimeSpan.FromMinutes(30)); + +OptimizelyFactory.SetCmabConfig(cmabConfig); +var optimizely = OptimizelyFactory.NewDefaultInstance("YOUR_SDK_KEY"); ``` -EventProcessor eventProcessor = new BatchEventProcessor.Builder() - .WithMaxBatchSize(MaxEventBatchSize) - .WithFlushInterval(MaxEventFlushInterval) - .WithEventDispatcher(eventDispatcher) - .WithNotificationCenter(notificationCenter) - .Build(); + +For details, see the [CMAB documentation](https://docs.developers.optimizely.com/feature-experimentation/docs/contextual-bandits). + +### ODP (Optimizely Data Platform) + +> Available in SDK 4.0.0+ for .NET Framework 4.5+ and .NET Standard 2.0+ + +ODP enables Advanced Audience Targeting: + +```csharp +// Fetch user segments +var user = optimizely.CreateUserContext("user123"); +await user.FetchQualifiedSegments(); +var decision = user.Decide("personalized_feature"); + +// Send custom events +optimizely.SendOdpEvent( + action: "purchase_completed", + identifiers: new Dictionary { { "vuid", "user123" } }, + data: new Dictionary { { "order_total", 99.99 } } +); ``` -##### Max Event Batch Size +For more details: +- [Advanced Audience Targeting](https://docs.developers.optimizely.com/feature-experimentation/docs/optimizely-data-platform-advanced-audience-targeting) +- [ODP segment qualification methods](https://docs.developers.optimizely.com/feature-experimentation/docs/advanced-audience-targeting-segment-qualification-methods-csharp) -The Max event batch size is used to limit eventQueue batch size and events will be dispatched when limit reaches. +### Feature Flags -##### Flush Interval +```csharp +// Check if feature is enabled +bool isEnabled = optimizely.IsFeatureEnabled("feature_key", "user123"); -The FlushInterval is used to specify a delay between consecutive flush events call. Event batch will be dispatched after meeting this specified timeSpan. +// Get feature variables +string value = optimizely.GetFeatureVariableString("feature_key", "variable_key", "user123"); +int intValue = optimizely.GetFeatureVariableInteger("feature_key", "count", "user123"); +double doubleValue = optimizely.GetFeatureVariableDouble("feature_key", "price", "user123"); +bool boolValue = optimizely.GetFeatureVariableBoolean("feature_key", "enabled", "user123"); +var jsonValue = optimizely.GetFeatureVariableJSON("feature_key", "config", "user123"); -##### Event Dispatcher +// Get all variables +var allVariables = optimizely.GetAllFeatureVariables("feature_key", "user123"); +``` -Custom EventDispatcher can be passed. +### Event Tracking -##### Notification Center +```csharp +// Track a conversion event +optimizely.Track("purchase", "user123"); -Custom NotificationCenter can be passed. +// Track with event tags +optimizely.Track("purchase", "user123", userAttributes, new EventTags +{ + { "revenue", 4200 }, + { "category", "electronics" } +}); +``` -#### HttpProjectConfigManager +### Forced Decisions -[`HttpProjectConfigManager`](https://github.com/optimizely/csharp-sdk/blob/master/OptimizelySDK/Config/HttpProjectConfigManager.cs) -is an implementation of the abstract [`PollingProjectConfigManager`](https://github.com/optimizely/csharp-sdk/blob/master/OptimizelySDK/Config/PollingProjectConfigManager.cs). -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. +Override decisions for QA and testing: -By default, `HttpProjectConfigManager` will block 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`. +```csharp +var user = optimizely.CreateUserContext("qa_user"); +var context = new OptimizelyDecisionContext("flag_key", "rule_key"); +var forcedDecision = new OptimizelyForcedDecision("variation_key"); -##### Use HttpProjectConfigManager +user.SetForcedDecision(context, forcedDecision); +user.RemoveForcedDecision(context); +user.RemoveAllForcedDecisions(); +``` +## Configuration + +### HttpProjectConfigManager + +```csharp +var configManager = new HttpProjectConfigManager.Builder() + .WithSdkKey("YOUR_SDK_KEY") + .WithPollingInterval(TimeSpan.FromMinutes(5)) + .WithBlockingTimeoutPeriod(TimeSpan.FromSeconds(15)) + .WithDatafileAccessToken("token") // For secure environments + .WithDatafile(fallbackDatafile) // Fallback datafile + .Build(); ``` -HttpProjectConfigManager httpManager = new HttpProjectConfigManager.Builder() - .WithSdkKey(sdkKey) - .WithPollingInterval(TimeSpan.FromMinutes(1)) - .Build(); + +| Parameter | Default | +|-----------|---------| +| PollingInterval | 5 minutes | +| BlockingTimeoutPeriod | 15 seconds | +| DatafileAccessToken | null | + +### BatchEventProcessor + +```csharp +var eventProcessor = new BatchEventProcessor.Builder() + .WithMaxBatchSize(10) + .WithFlushInterval(TimeSpan.FromSeconds(30)) + .Build(); ``` -##### SDK key +| Parameter | Default | +|-----------|---------| +| MaxBatchSize | 10 | +| FlushInterval | 30 seconds | +| TimeoutInterval | 5 minutes | -The SDK key is used to compose the outbound HTTP request to the default datafile location on the Optimizely CDN. +### App.config Configuration -##### Polling interval +```xml + + +
+ + + + + + +``` -The polling interval is used to specify a fixed delay between consecutive HTTP requests for the datafile. Between 1 to 4294967294 miliseconds is valid duration. Otherwise default 5 minutes will be used. +Then initialize: +```csharp +var optimizely = OptimizelyFactory.NewDefaultInstance(); +``` -##### Blocking Timeout Period +## Advanced Features -The blocking timeout period is used to specify a maximum time to wait for initial bootstrapping. Between 1 to 4294967294 miliseconds is valid blocking timeout period. Otherwise default value 15 seconds will be used. +### Notification Listeners -##### Initial datafile +```csharp +optimizely.NotificationCenter.AddNotification( + NotificationCenter.NotificationType.Decision, + (DecisionNotification notification) => { + Console.WriteLine($"Decision: {notification.Type}"); + } +); +``` -You can provide an initial datafile via the builder to bootstrap the `ProjectConfigManager` so that it can be used immediately without blocking execution. +**Notification Types:** `Decision`, `Track`, `LogEvent`, `OptimizelyConfigUpdate` -##### URL +### User Profile Service -The URL is used to specify the location of datafile. +Implement `UserProfileService` for sticky bucketing: -##### Format +```csharp +public class MyUserProfileService : UserProfileService +{ + public UserProfile Lookup(string userId) { /* ... */ } + public void Save(UserProfile userProfile) { /* ... */ } +} +``` -This option enables user to provide a custom URL format to fetch the datafile. +### OptimizelyConfig -##### Start by default +```csharp +var config = optimizely.GetOptimizelyConfig(); +foreach (var feature in config.FeaturesMap.Values) +{ + Console.WriteLine($"Feature: {feature.Key}"); +} +``` -This option is used to specify whether to start the config manager on initialization or not. If no value is provided, by default it is true and will start polling datafile from remote immediately. +### Disposal -##### Datafile access token +```csharp +optimizely.Dispose(); // Clean up resources -This option is used to provide token for datafile belonging to a secure environment. +// Or use with 'using' statement +using (var optimizely = OptimizelyFactory.NewDefaultInstance("SDK_KEY")) +{ + // Use SDK +} +``` ## SDK Development @@ -222,33 +340,32 @@ This option is used to provide token for datafile belonging to a secure environm Please see [CONTRIBUTING](CONTRIBUTING.md). +### Unit Tests + +```sh +dotnet test +``` + ### Third Party Licenses -Optimizely SDK uses third party software: -[murmurhash-signed](https://www.nuget.org/packages/murmurhash-signed/), -[Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/), and -[NJsonSchema](https://www.nuget.org/packages/NJsonSchema/). +- [murmurhash-signed](https://www.nuget.org/packages/murmurhash-signed/) +- [Newtonsoft.Json](https://www.nuget.org/packages/Newtonsoft.Json/) +- [NJsonSchema](https://www.nuget.org/packages/NJsonSchema/) -### Other Optimzely SDKs +## Credits -- Agent - https://github.com/optimizely/agent +This SDK is developed and maintained by [Optimizely](https://optimizely.com) and many [contributors](https://github.com/optimizely/csharp-sdk/graphs/contributors). -- Android - https://github.com/optimizely/android-sdk +### Other Optimizely SDKs +- Agent - https://github.com/optimizely/agent +- Android - https://github.com/optimizely/android-sdk - Flutter - https://github.com/optimizely/optimizely-flutter-sdk - - Go - https://github.com/optimizely/go-sdk - - Java - https://github.com/optimizely/java-sdk - - JavaScript - https://github.com/optimizely/javascript-sdk - - PHP - https://github.com/optimizely/php-sdk - - Python - https://github.com/optimizely/python-sdk - - React - https://github.com/optimizely/react-sdk - - Ruby - https://github.com/optimizely/ruby-sdk - - Swift - https://github.com/optimizely/swift-sdk