C# API (4.9)

7 minute read

Class Rox

namespace: Io.Rollout.Rox.Server.Rox

public class Rox

The Rox class provides your application with its primary interface for feature flags in the CloudBees Feature Management system. This is the central repository for your application’s flags. It handles communications with the server to obtain the latest values, implements experiment settings, and sets up configurations. It provides a mechanism through which you can use feature flags to control your application’s behavior. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values contained in the provided IRoxContainer will be marked as feature flags and will appear in your application’s CloudBees Feature Management dashboard 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 class 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.

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

Register

public static void Register(string namespace, 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.

Parameter Modifier and Type Description

namespace

string

The prefix namespace for all flags in this container

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.

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.

Class RoxOptions

namespace: Io.Rollout.Rox.Server

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,
    FetchInterval = 60,
    ConfigurationFetchedHandler = (sender, e) => {
        //TODO: add things to do when configuration was fetch
    },
    ImpressionHandler = (sender, e) => {
        //TODO: add things to do on impression
    },
    DynamicPropertiesRule = (property, context) => {
        //TODO: return dynamic rule for properties
    }
});
await Rox.Setup(appKey, options );

Class RoxOptions.RoxOptionsBuilder

namespace: Io.Rollout.Rox.Server

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.

FetchInterval

public int? FetchInterval { get; set; }

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

Logger

public ILogger Logger { get; set; }

Sets the Logger to be used for logging.

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

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.Server.Flag

public class RoxFlag : Flag

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 RoxVariant

namespace: Io.Rollout.Rox.Server.Flags

public class RoxVariant : Variant

RoxVariant is a feature flag object that can have values more complex than a simple boolean true or false. RoxVariant accepts a list of possible 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"};
RoxVariant TitleColorsVariant = new RoxVariant("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 variant’s value considering the given context.

Name

public string Name { get }

Get the variant name.

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 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 2 properties: the flag name and the value.

Property Description 
public string Name { get; }

The flag name.

 
public string Value {get; }

The evaluation result.

 
public Experiment Experiment { get; }

The experiment of the flag.

 
public string Name { get; }

Experiment name

 
public string Identifier { get; }

Experiment id

 
public boolean IsArchived { get; }

If the experiment is archived

 
public HashSet<String> Labels { get; }

Experiment’s labels that are assigned on the dashboard

 
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.

Java API
Python API