.NET/C# SDK reference

The following information is for the latest SDK version. If you are running an older version, please check the CloudBees platform changelog for any differences.

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

public static Task Setup(string apiKey)
public static Task Setup(string apiKey, RoxOptions options)▼

Set up the SDK with the application key.

Parameter Modifier and type Description

Parameter	Modifier and type	Description
`apiKey`	string	The CloudBees platform environment key.
`options`	RoxOptions	A `RoxOptions` instance with the desired configuration for this application.

apiKey

string

The CloudBees platform environment 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

public static async Task 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. All Register and SetCustomProperty then use a new Rox, and register the objects to the UI on the next setup call.

interface IRoxContainer

namespace: Io.Rollout.Rox.Core.Entities

public 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.

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

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

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

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

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.

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

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

public enum VerboseLevel
{
    Silent,
    Debug
}▼

Sets the logs verbosity level. The default is Silent.

SetCustomComputedBooleanProperty

public static void SetCustomComputedBooleanProperty(string name, CustomPropertyGenerator<boolean> generator)▼

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.

Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	CustomPropertyGenerator	An instance of the boolean property generator class

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

public static void SetCustomComputedDoubleProperty(string name, CustomPropertyGenerator<double> generator)▼

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.

Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	CustomPropertyGenerator	An instance of the double property generator class

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

public static void setCustomComputedIntegerProperty(string name, CustomPropertyGenerator<int> generator)▼

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.

Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	CustomPropertyGenerator	An instance of the Integer property generator class

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

public static void SetCustomComputedSemverProperty(string name, CustomPropertyGenerator<string> generator)▼

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.

Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	CustomPropertyGenerator	An instance of the string property generator class

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

public static void SetCustomComputedStringProperty(string name, CustomPropertyGenerator<string> generator)▼

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.

Parameter	Modifier and type	Description
name	string	The name of the property to create
generator	CustomPropertyGenerator	An instance of the string property generator class

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

public static void SetCustomBooleanProperty(string name, boolean value)▼

Sets a custom property representing a boolean value.

Parameter Modifier and type Description

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`

name

string

The name of the custom property

value

boolean

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

SetCustomDoubleProperty

public static void SetCustomDoubleProperty(string name, double value)▼

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

Parameter	Modifier and type	Description
name	string	The property name
value	double	The value of the property

Parameter

Modifier and type

Description

name

string

The property name

value

double

The value of the property

SetCustomIntegerProperty

public static void SetCustomIntegerProperty(string name,int value)▼

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

Parameter	Modifier and type	Description
name	string	The property name
value	int	The value of the property

Parameter

Modifier and type

Description

name

string

The property name

value

int

The value of the property

SetCustomSemverProperty

public static void SetCustomSemverProperty(string name, string value)▼

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

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.

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

public static void SetCustomStringProperty(String name,String value)▼

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

Parameter	Modifier and type	Description
name	string	The name of the property to create
value	string	The property value

Parameter

Modifier and type

Description

name

string

The name of the property to create

value

string

The property value

SetContext

public static void SetContext(IContext context)▼

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

Fetch

async public static Task Fetch()▼

Creates a network request for the latest configuration.

IsTargetingOnForFlag

public static bool IsTargetingOnForFlag(string flagName)▼

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.

SetUserspaceUnhandledErrorHandler

public static void SetUserspaceUnhandledErrorHandler(UserspaceUnhandledErrorHandler userspaceUnhandledErrorHandler);
public delegate void UserspaceUnhandledErrorHandler(UserspaceUnhandledErrorArgs args);▼

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.

CloudBees recommends wrapping all user methods with try-catch to handle errors while in the relevant context, rather than afterward.

UserspaceUnhandledErrorArgs

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

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

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

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

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

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

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

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

public ReportingValue ReportingValue { get; }▼

This object has three properties:

The flag name
The flag value
Whether the flag configuration is on or off

Property Description

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 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

public DynamicPropertiesRule DynamicPropertiesRule { get; set; }▼

DynamicPropertiesRule(string propName, IContext context)▼

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.

return (propName, context) => context != null ? context.Get(propName) : null;▼

RoxyURL

public Uri RoxyURL { get; set; }▼

A roxy URL.

Proxy

public IWebProxy Proxy { get; set; }▼

A proxy configuration to send all network requests.

new WebProxy(<url>, false, null, new NetworkCredential(<user>, <password>))▼

interface IContext

namespace: Io.Rollout.Rox.Core.Context

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.

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

object Get(string key);▼

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

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

Rox.DynamicApi()

public static Core.Client.IDynamicApi 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.

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.

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.

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.

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.

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

async public static Task Fetch()▼

Creates a network request for the latest configuration.

SetContext

public static void SetContext(IContext context)▼

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.

SetUserspaceUnhandledErrorHandler

public static void SetUserspaceUnhandledErrorHandler(UserspaceUnhandledErrorHandler userspaceUnhandledErrorHandler);
public delegate void UserspaceUnhandledErrorHandler(UserspaceUnhandledErrorArgs args);▼

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.

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

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; }▼