.NET/C# (server-side) SDK reference

12 minute readReference

The following information is for the latest SDK version (6.x). The CloudBees platform requires that your installed SDK version be at least 6.x. Please install the latest SDK by following the instructions in the platform UI or in the SDK installation documentation.

Any updates to version 6.x are noted in the platform changelog.

Class Rox

namespace: Io.Rollout.Rox.Server

public class Rox
▼

The Rox class provides an interface for feature management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This class handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. It works with a RoxContainer-derived object that holds your application’s feature flags. The values in the provided IRoxContainer are marked as feature flags and displayed in the UI once the application is run.

This class also allows you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or you can use a generator function to provide a custom property that is dependent upon code state. These generated properties must derive from CustomPropertyGenerator, which is a template class.

You can use a RoxOptions object to configure some aspects of this class. Set the verbosity level, custom platform, global freeze level, impression handler, and fetch handler.

Setup

Set up the SDK with the environment-specific SDK key provided by the platform UI.

public static Task Setup(string apiKey)
public static Task Setup(string apiKey, RoxOptions options)
▼
Parameter Modifier and type Description

apiKey

string

The CloudBees platform environment-specific SDK key.

options

RoxOptions

A RoxOptions instance with the desired configuration for this application.
Further Setup calls after Rox is set are ignored, unless the last setup failed, or unless Rox Shutdown is invoked.

Shutdown

Performs graceful shutdown of the Rox object; this closes and cleans all background tasks and threads. Use Shutdown only when Rox is set up successfully. Calling Shutdown when it is not possible results in a log warning. You can call Setup again after Shutdown. In that case, Register and SetCustomProperty then use a new Rox, and register the objects to the UI on the next setup call.

public static async Task Shutdown()
▼

interface IRoxContainer

The IRoxContainer is an interface describing a feature flag container for a CloudBees platform-enabled application. The IRoxContainer implementation class for your application contains all the feature flags in your application. These feature flags are converted into CloudBees platform flags when the container is registered with Rox using Rox.Register(). Feature flag names are derived from the provided flag variable names.

namespace: Io.Rollout.Rox.Core.Entities

public interface IRoxContainer

Use as in the following example:

public class MyContainer : IRoxContainer
{
  public RoxFlag includeFacebook = new RoxFlag();
  public RoxFlag includeGithub = new RoxFlag();
}

// Include this code as early as possible in your program's initialization code
RoxContainer conf = new MyContainer();

// Registers the container with {PRODUCT}, creating relevant flags in the {PRODUCT} system
Rox.Register("", conf);

await Rox.Setup(environmentKey);
▼

Register

Registers a feature flag container with the Rox client. The public member variables of this container become a flag in the UI.

public static void Register(string namespace, IRoxContainer container);
public static void Register(IRoxContainer container);
▼

  • A namespace can only be registered once. Attempting to use the same namespace again throws an exception.

  • DynamicApi can be used as an alternative to static containers.
Parameter Modifier and type Description

namespace

String

The prefix namespace for all flags in this container. If no namespace is provided, the namespace defaults to an empty string.

container

IRoxContainer

An object derived from RoxContainer that contains your application’s feature flags.

For example, assuming the following container:

public class MyContainer : IRoxContainer
{
  public RoxFlag includeFacebook = new RoxFlag();
  public RoxFlag includeGithub = new RoxFlag();
}
▼

and the container is registered as in the following:

RoxContainer conf = new MyContainer();
Rox.Register("Login", conf);
await Rox.Setup(environmentKey);
▼

The flag in the UI has the names Login.includeFacebook and Login.includeGithub. This is useful for setting up groups of flags.

Class RoxFlag

namespace: Io.Rollout.Rox.Server.Flag

public class RoxFlag
▼

RoxFlag is a Boolean feature flag. It can be either true or false.

IsEnabled

public bool IsEnabled(Context = null)
▼

Returns true if the flag is enabled.

Name

public string Name { get; }
▼

The name of the flag.

Class RoxString

namespace: Io.Rollout.Rox.Server.Flags

public class RoxString
▼

RoxString is a feature flag object that accepts a list of possible string values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

For example:

String[] TitleColorsOptions = new String[] {"Black", "Blue", "Green"};
RoxString TitleColorsVariant = new RoxString("Black", TitleColorsOptions);

if (TitleColorsVariant.GetValue().Equals("Black"))
{
    // set title color to black
}
else if (TitleColorsVariant.GetValue().Equals("Green"))
{
    // set title color to green
}
▼

GetValue

public string GetValue(IContext context = null)
▼

Returns the RoxString value considering the given context.

Name

public string Name { get }
▼

The RoxString name.

Class RoxInt

namespace: Io.Rollout.Rox.Server.Flags

public class RoxInt
▼

RoxInt is a feature flag object that accepts a list of possible integer values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

For example:

int[] TitleSizeOptions = new int[] {14, 18, 24};
RoxInt TitleColorsVariant = new RoxInt(14, TitleSizeOptions);

var titleSize = TitleColorsVariant.GetValue();
▼

GetValue

public int GetValue(IContext context = null)
▼

Returns the RoxInt value considering the given context.

Name

public string Name { get }
▼

The RoxInt name.

Class RoxDouble

namespace: Io.Rollout.Rox.Server.Flags

public class RoxDouble
▼

RoxDouble is a feature flag object that accepts a list of possible double values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

For example:

double[] PriceOptions = new double[] {19.99, 29.99, 40.5};
RoxDouble PriceVariant = new RoxDouble(19.99, PriceOptions);

var price = PriceVariant.GetValue();
▼

GetValue

public double GetValue(IContext context = null)
▼

Returns the RoxDouble’s value considering the given context.

Name

public string Name { get }
▼

The RoxDouble name.

Class RoxOptions

namespace: Io.Rollout.Rox.Server

public class RoxOptions : IRoxOptions

RoxOptions includes configuration options for the Rox client, including settings such as the verbosity of the logging. Create instances of this class with RoxOptions.Builder.

Use as in the following example that sets the version, includes a logger, provides an impression handler, and sets up a fetch handler.

RoxOptions options = new RoxOptions(new RoxOptions.RoxOptionsBuilder{
Version = "1.0.4",
Logger = applicationLog,
ConfigurationFetchedHandler = (sender, e) => {
//TODO: add things to do when configurations were fetched
},
ImpressionHandler = (sender, e) => {
//TODO: add things to do on impression
},
DynamicPropertiesRule = (property, context) => {
//TODO: return dynamic rule for properties
},
BaseCachePath = "/Users/Me/SomeUser", // Local path with permissions
Proxy = new WebProxy(new Uri("https://companyProxy"))
});
await Rox.Setup(appKey, options );
▼

Class RoxOptions.RoxOptionsBuilder

namespace: Io.Rollout.Rox.Server

public static class RoxOptionsBuilder
▼

Use this builder class to create a new RoxOptions instance.

Version

public string Version { get; set; }
▼

Sets the version of the service running the CloudBees platform SDK.

FetchInterval

public int? FetchInterval { get; set; }
▼

Sets the polling interval for fetching the configuration from the CloudBees platform storage service. The default time is 60 seconds, and the minimum is 30 seconds.

BaseCachePath

public string BaseCachePath { set; get; }
▼

Sets a path for local storage. Defaults to the path System.Environment.SpecialFolder.LocalApplicationData. Flag configuration files are saved and loaded from <BaseCachePath>/CloudbeesFM/<app_key>/configuration.json. A successful configuration fetch overrides the file at this path. Be sure to verify that you have the appropriate permissions.

Logger

public ILogger Logger { get; set; }
▼

Sets up the logger to generate log files.

VerboseLevel

Sets the logs verbosity level. The default is Silent.

public VerboseLevel VerboseLevel { get; set; } = VerboseLevel.Silent;

public enum VerboseLevel
{
    Silent,
    Debug
}
▼

SetCustomComputedBooleanProperty

Sets a computed Boolean custom property on the Rox client. This is a computable Boolean, with an object that generates the value for the property. The generator must be a delegate of type CustomPropertyGenerator in rox-core.

public static void SetCustomComputedBooleanProperty(string name, CustomPropertyGenerator<boolean> generator)
▼
Parameter Modifier and type Description

name

string

The name of the property to create

generator

CustomPropertyGenerator

An instance of the Boolean property generator class

SetCustomComputedDoubleProperty

Sets a computed double custom property on the Rox client. This is a computable double, with an object that generates the value for the property. The generator must be a delegate of type CustomPropertyGenerator in rox-core.

public static void SetCustomComputedDoubleProperty(string name, CustomPropertyGenerator<double> generator)
▼
Parameter Modifier and type Description

name

string

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the double property generator class.

SetCustomComputedIntegerProperty

Sets a computed integer custom property on the Rox client. This is a computable integer, with an object that generates the value for the property. The generator must be a delegate of type CustomPropertyGenerator in rox-core.

public static void setCustomComputedIntegerProperty(string name, CustomPropertyGenerator<int> generator)
▼
Parameter Modifier and type Description

name

string

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the Integer property generator class.

SetCustomComputedSemverProperty

Sets a computed semantic-versioned string custom property on the Rox client. This is a computable semantically-versioned string, with an object that generates the value for the property. The generator must be a delegate of type CustomPropertyGenerator in rox-core.

public static void SetCustomComputedSemverProperty(string name, CustomPropertyGenerator<string> generator)
▼
Parameter Modifier and type Description

name

string

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property generator class.

SetCustomComputedStringProperty

Sets a computed string custom property on the Rox client. This is a computable string, with an object that generates the value for the property. The generator must be a delegate of type CustomPropertyGenerator in rox-core.

public static void SetCustomComputedStringProperty(string name, CustomPropertyGenerator<string> generator)
▼
Parameter Modifier and type Description

name

string

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property generator class.

SetCustomBooleanProperty

Sets a custom property representing a Boolean value.

public static void SetCustomBooleanProperty(string name, Boolean value)
▼
Parameter Modifier and type Description

name

string

The name of the custom property.

value

boolean

The value for the custom property, as a Boolean true or false.

SetCustomDoubleProperty

Sets a custom property that can store a specified double value.

public static void SetCustomDoubleProperty(string name, double value)
▼
Parameter Modifier and type Description

name

string

The property name

value

double

The value of the property

SetCustomIntegerProperty

Sets a custom property that can store a specified integer value.

public static void SetCustomIntegerProperty(string name,int value)
▼
Parameter Modifier and type Description

name

string

The property name

value

int

The value of the property

SetCustomSemverProperty

Sets a custom property that uses a specified semantic version as its value. Refer to the Semantic Versioning documentation for more information.

public static void SetCustomSemverProperty(string name, string value)
▼
Parameter Modifier and type Description

name

string

The name of the property to create

value

string

The property value, formatted using the rules defined in the Semantic Versioning documentation.

SetCustomStringProperty

Sets a custom string property for the Rox client, which is a string property you can fetch by name.

public static void SetCustomStringProperty(String name,String value)
▼
Parameter Modifier and type Description

name

string

The name of the property to create

value

string

The property value

SetContext

Sets a global context. This context is available to all flag evaluations.

public static void SetContext(IContext context)
▼

Fetch

Creates a network request for the latest configuration.

async public static Task Fetch()
▼

IsTargetingOnForFlag

Returns whether the flag targeting configuration is on or off. Not to be confused with the flag value (isEnabled). Throws an exception if Rox has not yet successfully loaded flag configurations.

public static bool IsTargetingOnForFlag(string flagName)
▼

SetUserspaceUnhandledErrorHandler

A handler for all user function errors, to assist in debugging and understanding unexpected flag values. If this function is not set, errors are logged to the logger.

public static void SetUserspaceUnhandledErrorHandler(UserspaceUnhandledErrorHandler userspaceUnhandledErrorHandler);
public delegate void UserspaceUnhandledErrorHandler(UserspaceUnhandledErrorArgs args);
▼
CloudBees recommends wrapping all user methods with try-catch to handle errors while in the relevant context, rather than afterward.

UserspaceUnhandledErrorArgs

The following are to manage exceptions.

public ExceptionTrigger exceptionTrigger { get; }
▼

An enum for the user delegate type:

public enum ExceptionTrigger
{
    DynamicPropertiesRule,
    ConfigurationFetchedHandler,
    ImpressionHandler,
    CustomPropertyGenerator
}
▼

The delegate that raised the exception:

public object exceptionSource { get; }
▼

The original exception thrown in the user delegate:

public Exception exception { get; }
▼

ConfigurationFetchedHandler

Sets the configuration event handler used to add actions after fetching configurations.

public EventHandler<ConfigurationFetchedArgs> ConfigurationFetchedHandler { get; set; }
▼

Using ConfigurationFetchedHandler

The ConfigurationFetchedHandler delegate/method you provide to RoxOptions has some useful parameters which can help you decide on further actions.

This EventHandler data type is ConfigurationFetchedArgs.

ConfigurationFetchedArgs class

Use as follows:

public FetcherStatus FetcherStatus { get; }
▼

An enum indicates the fetch result:

public enum FetcherStatus
{
    AppliedFromEmbedded,
    AppliedFromLocalStorage,
    AppliedFromNetwork,
    ErrorFetchedFailed
}
▼

The following example gets the time the fetched configurations are created and signed:

public DateTime CreationDate { get; }
▼

Use a Boolean to determine if the fetched configurations are different from the latest ones (at setup this is always true):

public bool HasChanges { get; }
▼

Use an enum as below to determine which error occurred while fetching and setting up new configurations. NoError specifies that the configurations are fetched and loaded.

public FetcherError ErrorDetails { get; }

public enum FetcherError
{
    CorruptedJson,
    EmptyJson,
    SignatureVerificationError,
    NetworkError,
    MismatchAppKey,
    Unknown,
    NoError
}
▼

ImpressionHandler

Sets the impression event handler used to add actions after an impression.

public EventHandler<ImpressionArgs> ImpressionHandler { get; set; }
▼

Using ImpressionHandler

The impressionHandler delegate/method you provide to RoxOptions has some useful parameters which can help you decide on further actions.

This EventHandler data type is ImpressionArgs.

ImpressionArgs class

This object has three properties:

  • The flag name

  • The flag value

  • Whether the flag configuration is on or off

public ReportingValue ReportingValue { get; }
▼
Property Description 
public string Name { get; }
▼

The flag name.

 
public string Value {get; }
▼

The evaluation result.

 
public bool Targeting {get; }
▼

Whether targeting is on or off.

 
public IContext Context { get; }
▼

The context in which the impression is called (this is a merged context containing both the global context and the context of the call).

DynamicPropertiesRule

The dynamic custom property generator is called when an explicit custom property definition does not exist on the client side.

If you do not set the setDynamicCustomPropertyRule, it activates the default function, which then attempts to extract the property value from context.

public DynamicPropertiesRule DynamicPropertiesRule { get; set; }
▼
DynamicPropertiesRule(string propName, IContext context)
▼
return (propName, context) => context != null ? context.Get(propName) : null;
▼

RoxyURL

A roxy URL.

public Uri RoxyURL { get; set; }
▼

Proxy

A proxy configuration to send all network requests.

public IWebProxy Proxy { get; set; }
▼
new WebProxy(<url>, false, null, new NetworkCredential(<user>, <password>))
▼

interface IContext

The context object is used to pass data to the flag when checking if the current flag is enabled or disabled. This object is used by the registered custom properties to evaluate the flag configuration and return the flag value.

namespace: Io.Rollout.Rox.Core.Context

Create a context with ContextBuilder and send a dictionary to its build function, as in the following example:

var context = new ContextBuilder().Build(new Dictionary<string, object> { { "userName", name } });
▼

Get

This function is used to retrieve data from the context. In the following example, the SetComputedStringProperty is using the context to get the username.

object Get(string key);
▼
Rox.SetCustomComputedStringProperty("user_name", (context) => context.Get("userName").ToString());
▼

Rox.DynamicApi()

Rox.DynamicApi() is an alternative to using a container with Register. It enables you to evaluate flags without having a static container. The dynamicApi creates flags as if they were registered, and they display in the UI.

public static Core.Client.IDynamicApi DynamicApi()
▼

isEnabled

Evaluate a Boolean flag as follows:

bool IsEnabled(string name, bool defaultValue, IContext context = null);
▼
Name Type Description

name

string

The flag name. Throws an error if null.

defaultValue

Boolean

The default value to use if there are no dashboard configurations.

context

IContext

A context to evaluate the flag with. This context is merged with the global context.

GetValue

Evaluate a string flag as follows:

string GetValue(string name, string defaultValue, IEnumerable<string> variations, IContext context = null);
▼
Name Type Description

name

string

The flag name. Throws an error if null.

defaultValue

string

The default value to use if there are no dashboard configurations, or if the value is set to the default in the UI. Throws an error if null.

context

IContext

A context to evaluate the flag with. This context is merged with the global context.

variations

IEnumerable<string>

All alternative values for use in the UI. Can be changed in the UI.

GetInt

Evaluate an integer number flag as follows:

int GetInt(string name, int defaultValue, IEnumerable<int> variations, IContext context = null);
▼
Name Type Description

name

string

The flag name. Throws an error if null.

defaultValue

int

The default value to use if there are no dashboard configurations, or if the value is set to the default in the UI. Throws an error if null.

context

IContext

A context to evaluate the flag with. This context is merged with the global context.

variations

IEnumerable<int>

All alternative values for use in the UI. Can be changed in the UI.

GetDouble

Evaluate a double number flag as follows:

int GetDouble(string name, double defaultValue, IEnumerable<double> variations, IContext context = null);
▼
Name Type Description

name

string

The flag name. Throws an error if null.

defaultValue

double

The default value to use if there are no dashboard configurations, or if the value is set to the default in the UI. Throws an error if null.

context

IContext

A context to evaluate the flag with. This context is merged with the global context.

variations

IEnumerable<double>

All alternative values for use in the UI. Can be changed in the UI.

Fetch

Creates a network request for the latest configuration.

async public static Task Fetch()
▼

SetContext

Sets the global evaluation context. This context is merged with the local one when evaluating flag conditions. Values from local context have precedence over globally set values.

public static void SetContext(IContext context)
▼

SetUserspaceUnhandledErrorHandler

Sets a handler for exceptions triggered by user-defined functions, to assist in understanding unexpected flag values. In case this function is not set, errors are logged to the logger.

public static void SetUserspaceUnhandledErrorHandler(UserspaceUnhandledErrorHandler userspaceUnhandledErrorHandler);
public delegate void UserspaceUnhandledErrorHandler(UserspaceUnhandledErrorArgs args);
▼
CloudBees recommends that you wrap all user methods with try-catch in order to handle it while in the relevant context, rather than afterward.

UserspaceUnhandledErrorArgs

Use as follows:

public ExceptionTrigger exceptionTrigger { get; }
▼

An enum for the user delegate type:

public enum ExceptionTrigger
{
    DynamicPropertiesRule,
    ConfigurationFetchedHandler,
    ImpressionHandler,
    CustomPropertyGenerator
}
▼

The delegate which raises the exception:

public object exceptionSource { get; }
▼

The original exception thrown in the user delegate:

public Exception exception { get; }
▼
JavaScript SSR
NodeJS