C# Client API

14 minute readReference

The following information is for the latest version of the C# Client SDK. If you are running an older version, please check the CloudBees Feature Management - C# changelog for any differences.

Class Rox

namespace: Io.Rollout.Rox.Client

public class Rox
▼

The Rox class provides an interface for CloudBees 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, which holds your application’s feature flags. The values in the provided IRoxContainer are marked as feature flags and display in the CloudBees Feature Management 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. Alternatively, 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 also use a RoxOptions object to configure some aspects of this class. You can set the verbosity level, custom platform, global freeze level, impression handler, or fetch handler.

Setup

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

Configures the Rox object to work with the provided application. Further Setup calls after the first one will be ignored, unless Rox was Shutdown first. Setup will wait only for local storage configurations; in order to wait for network result, use Configuration fetched handler.

Parameter Modifier and Type Description

apiKey

string

The environment key provided by the dashboard

options

RoxOptions

A RoxOptions instance with the desired configuration for this application

Shutdown

public static async Task Shutdown()
▼

This method allows for the graceful shutdown of the Rox object, and will close and clean all background tasks and threads. It can only be used when Rox is successfully Setup.

Calling Shutdown when it’s not possible, will result a log warning.

You can call Setup again after Shutdown; right after Shutdown, all Register and SetCustomProperty will use a new Rox, and will register the objects to the Dashboard on the next Setup call.

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 will become flags in your CloudBees Feature Management dashboard.

  • A namespace can only be registered once; trying to use the same namespace twice will throw 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 (defaults to "")

container

IRoxContainer

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

Example

Assuming we have the following container:

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

Then register the container with the following code:

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

The flag and configuration in the dashboard will have the names Login.includeFacebook and Login.includeGithub. This is very handy if you want to have groups of flags or configurations.

If you don’t need a namespace, you can set the namespace to an empty string.

Resume

public static async Task Resume()
▼

This method can be called when Application goes back to foreground (from background). It will force a configuration Fetch, and will Unfreeze all frozen flags.

Example

await Rox.Resume();

unfreeze

public static void Unfreeze(string @namespace = null)
▼

Unfreeze the state of all flags.

Calling this function will unfreeze all flags. If a namespace was specified, this will effect only the this namespace. After unfreeze using a flag will return its most updated value.

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 should 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’s 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 should 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’s 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 should 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’s 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 should 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’s generator class

SetCustomComputedStringProperty

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

Sets a custom computed string property on the Rox client. This is a computable string, with an object that generates the value for the property. The generator should 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’s generator class

SetCustomBooleanProperty

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

Sets a custom property representing a 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

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

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

SetCustomSemverProperty

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

Sets a Custom Property that uses a semantic version as its value. See https://semver.org/ for more information on Semantic Versioning.

Parameter Modifier and Type Description

name

string

The name of the property to create

value

string

The property value, formatted using the rules defined at semver.org

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’s value

SetContext

public static void SetContext(IContext context)
▼

Sets a global context. This context will be available to all flags' evaluations.

Fetch

async public static Task Fetch()
▼

Creates a network request for the latest configuration.

IsTargetingOnForFlag

public static bool IsTargetingOnForFlag(string flagName)
▼

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

SetUserspaceUnhandledErrorHandler

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

A handler for all user function errors, which might help you debug and understand unexpected flag values. In case this function is not set, errors will be logged to the logger. Note: it is recommended to wrap all user methods with try-catch in order to handle it while in the relevant context, and not afterward.

UserspaceUnhandledErrorArgs

public ExceptionTrigger exceptionTrigger { get; }
▼

An enum for the user delegate type

public enum ExceptionTrigger
{
    DynamicPropertiesRule,
    ConfigurationFetchedHandler,
    ImpressionHandler,
    CustomPropertyGenerator
}
▼
public object exceptionSource { get; }
▼

The delegate which raised the exception

public Exception exception { get; }
▼

The original exception that was thrown in the user delegate

Class RoxOptions

namespace: Io.Rollout.Rox.Client

public class RoxOptions : IRoxOptions

RoxOptions covers configuration options for the Rox client. This includes settings like the verbosity of the logging. Instances of this class should be created using RoxOptions.Builder.

Example

Here is an example of setting up a new RoxOptions object. This options object 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.Client

public static class RoxOptionsBuilder
▼

This builder class is used to create a new RoxOptions instance.

Version

public string Version { get; set; }
▼

Sets the version of the service running CloudBees Feature Management SDK.

BaseCachePath

public string BaseCachePath { set; get; }
▼

Sets a path for a 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. Please verify that you have the appropriate permissions.

Logger

public ILogger Logger { get; set; }
▼

Sets the Logger to be used for logging.

Platform

public string Platform { get; set; }
▼

Sets a customized platform

DevModeSecret

public string DevModeKey { get; set; }
▼

Add security, to prevent client of creating object on Dashboard (see Security documentation)

Freeze

public Freeze? Freeze { get; set; }

public enum Freeze
{
    UntilLaunch = 1,
    UntilForeground = 2,
    None = 3
}
▼

Sets the default freeze level, for Flags without Freeze Option (default: None)

VerboseLevel

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

public enum VerboseLevel
{
    Silent,
    Debug
}
▼

Sets logs verbose level (default: Silent)

ConfigurationFetchedHandler

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

Sets the configuration event handler that is used to add actions after configurations were fetched.

ImpressionHandler

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

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

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 will then activate the default function which tries 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 (see Microservices automated testing and local development).

Proxy

public IWebProxy Proxy { get; set; }
▼

A proxy configuration for all network requests to be sent to. To use with a proxy server, refer to Using a proxy for more information.

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

interface IRoxContainer

namespace: Io.Rollout.Rox.Core.Entities

public interface IRoxContainer

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

Example

Below is a quick example of how to use this container class:

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

Class RoxFlag

namespace: Io.Rollout.Rox.Client.Flag

public class RoxFlag
▼
public RoxFlag(Freeze? freeze = null) // defaultValue default: false
public RoxFlag(bool defaultValue, Freeze? freeze = null)
▼

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.

Unfreeze

public void Unfreeze(Freeze freeze = Flags.Freeze.UntilLaunch)
▼

Unlock the flag value from changes from the last time it was frozen.

Class RoxString

namespace: Io.Rollout.Rox.Client.Flags

public class RoxString
▼
public RoxString(string defaultValue, Freeze? freeze = null)
public RoxString(string defaultValue, IEnumerable<string> options = null, Freeze? freeze = null)
▼

RoxString is a feature flag object that can have string values. RoxString accepts a list of possible string values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard.

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’s value considering the given context.

Name

public string Name { get }
▼

Get the RoxString name.

public void Unfreeze(Freeze freeze = Flags.Freeze.UntilLaunch)
▼

Unlock the flag value from changes from the last time it was frozen.

Class RoxInt

namespace: Io.Rollout.Rox.Client.Flags

public class RoxInt
▼
public RoxInt(int defaultValue, Freeze? freeze = null)
public RoxInt(int defaultValue, IEnumerable<int> variations, Freeze? freeze = null)
▼

RoxInt is a feature flag object that can have int values. RoxInt accepts a list of possible int values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard.

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’s value considering the given context.

Name

public string Name { get }
▼

Get the RoxInt name.

public void Unfreeze(Freeze freeze = Flags.Freeze.UntilLaunch)
▼

Unlock the flag value from changes from the last time it was frozen.

Class RoxDouble

namespace: Io.Rollout.Rox.Client.Flags

public class RoxDouble
▼
public RoxDouble(double defaultValue, Freeze? freeze = null)
public RoxDouble(double defaultValue, IEnumerable<double> variations, Freeze? freeze = null)
▼

RoxDouble is a feature flag object that can have double values. RoxDouble accepts a list of possible double values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard.

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

Get the RoxDouble name.

public void Unfreeze(Freeze freeze = Flags.Freeze.UntilLaunch)
▼

Unlock the flag value from changes from the last time it was frozen.

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 experiment expression and return the flag value.

You can create a context using the ContextBuilder and sending a dictionary to its build function.

Example

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

Get

object Get(string key);
▼

This get function is used to retrieve data from the context.

Example

In this example, you can see how the SetComputedStringProperty is using the context to get the username.

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

Using ConfigurationFetchedHandler

The ConfigurationFetchedHandler delegate/method (you can provide to RoxOptions) has a couple of 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
}
▼
public DateTime CreationDate { get; }
▼

The time the fetched configurations were created and signed

public bool HasChanges { get; }
▼

A boolean indicates if the fetched configurations are different from the latest ones (On setup this will always be true)

public FetcherError ErrorDetails { get; }
▼

An enum presenting which error occured while fetching and setting up the new configurations. NoError means the configurations were fetched and loaded

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

For an example, see Fetched handler.

Using ImpressionHandler

The impressionHandler delegate/method (you can provide to RoxOptions) has a couple of 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 3 properties: the flag name, the value, and targeting indicating whether the flag has configurations targeting on or off.

Property Description 
public string Name { get; }
▼

The flag name.

 
public string Value {get; }
▼

The evaluation result.

 
public bool Targeting {get; }
▼

is targeting on or off

 
public IContext Context { get; }
▼

The context in which the impression was called (this is a merged context containing the global context, and the call’s context).

For an example, see Impression handler.

Rox.Overrides

public static FlagOverrides Overrides
▼

Rox.Overrides is used to override a flag value locally, it is used by developers working on a feature in dev mode and shouldn’t be used in production builds.

It is the base API that is used to show the Flag update flow. It is Currently this SDK doesn’t have UI support that wraps overrides The only way to use overrides is by code

When you override an existing flag value using the Rox.Overrides.setOverride method, the SDK will disregard existing configuration coming from the dashboard and will serialize the override on disk this value will be loaded and override the flag right after you call Rox.Setup. To clear the override from the cache you need to call the Rox.Overrides.Clear method.

Rox.Overrides.setOverride

public void SetOverride(string flagName, string flagValue)
▼

Sets an override value on a specific flag, this function accepts two parameters flag name (full flag name including namespace) and desired value (from type String).

This function also saves the override value on the local device disk, so it is "remembered" for the next the SDK is loaded to production.

Parameter Type Description

flagName

String

full flag name including namespace, eg. default.flagName

flagValue

String

The value of a flag, if this is a boolean flag the value should be "true"

Rox.Overrides.ClearOveride

public void ClearOverride(string flagName)
public void ClearOverride()
▼

Clears the override value from the flag (and the disk). After calling SetOverride function the override value is serialized on the disk, this function is used to clear this override value.

Parameter Type Description

flagName

String

full flag name including namespace, eg. default.flagName

Rox.Overrides.HasOverride

public bool HasOverride(string flagName)
▼

Returns true if a flag has an override.

Parameter Type Description

flagName

String

full flag name including namespace, eg. default.flagName

Return Value

Type : boolean - true if flag has an override in place

Rox.Overrides.GetOriginalValue

public string GetOriginalValue(string flagName)
▼

Returns the current flag value regardless of Overrides. Will not trigger freeze or impression. If the flag is frozen, the frozen value will be returned.

Parameter Type Description

flagName

String

full flag name including namespace, eg. default.flagName

Return Value

Value : string - the flag value in a string form

Rox.Overrides.PeekCurrentValue

public string PeekCurrentValue(string flagName)
▼

Returns the current flag value. Will not trigger freeze or impression. If the flag is frozen, the frozen value will be returned.

Parameter Type Description

flagName

String

full flag name including namespace, eg. default.flagName

Return Value

Value : string - the flag value in a string form

Rox.DynamicApi()

public static Core.Client.IDynamicApi DynamicApi()
▼

An alternative of using container with register. This allows you to evaluate flags without having a static container. DynamicApi will create flags as if they were registered, including sending them to the dashboard.

See also Dynamic api.

isEnabled

Evaludate a boolean flag

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

name

type

description

name

string

the flag’s name - throws an error if null

defaultValue

boolean

the default value to use if no dashboard configurations

context

IContext

a context to evalute the flag with, will be merged with the global context

GetValue

Evaluate a string flag

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

name

type

description

name

string

the flag’s name - throws an error if null

defaultValue

string

the default value to use if no dashboard configurations, or value was set to default on dashboard throws an error if null

variations

IEnumerable<string>

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

IContext

a context to evalute the flag with, will be merged with the global context

GetInt

Evaluate an int flag

int GetInt(string name, int defaultValue, IEnumerable<int> variations, IContext context = null);
▼
name type description

name

string

the flag’s name - throws an error if null

defaultValue

int

the default value to use if no dashboard configurations, or value was set to default on dashboard

variations

IEnumerable<int>

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

IContext

a context to evaluate the flag with, will be merged with the global context

GetDouble

Evaluate a double flag

int GetDouble(string name, double defaultValue, IEnumerable<double> variations, IContext context = null);
▼
name type description

name

string

the flag’s name - throws an error if null

defaultValue

double

the default value to use if no dashboard configurations, or value was set to default on dashboard

variations

IEnumerable<double>

all alternative values to use on the dashboard (can be changed on the dashboard side)

context

IContext

a context to evalute the flag with, will be merged with the global context
C# API
Go API