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 |
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 |
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.
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.
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 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.
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.
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 |
---|---|
|
The flag name. |
|
The evaluation result. |
|
The experiment of the flag. |
|
Experiment name |
|
Experiment id |
|
If the experiment is archived |
|
Experiment’s labels that are assigned on the dashboard |
|
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.