Class LdClient

A client for the LaunchDarkly API. Client instances are thread-safe. Applications should instantiate a single LdClient for the lifetime of their application.

Inheritance

object

LdClient

Implements

IDisposable

ILdClient

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: LaunchDarkly.Sdk.Server

Assembly: LaunchDarkly.ServerSdk.dll

Syntax

public sealed class LdClient : IDisposable, ILdClient

Constructors

LdClient(Configuration)

Creates a new client to connect to LaunchDarkly with a custom configuration.

Declaration

public LdClient(Configuration config)

Parameters

Type	Name	Description
Configuration	config	a client configuration object (which includes an SDK key)

Remarks

Applications should instantiate a single instance for the lifetime of the application. In unusual cases where an application needs to evaluate feature flags from different LaunchDarkly projects or environments, you may create multiple clients, but they should still be retained for the lifetime of the application rather than created per request or per thread.

Normally, the client will begin attempting to connect to LaunchDarkly as soon as you call the constructor. The constructor returns as soon as any of the following things has happened:

1. It has successfully connected to LaunchDarkly and received feature flag data. In this case, Initialized will be true, and the DataSourceStatusProvider will return a state of Valid.
2. It has not succeeded in connecting within the StartWaitTime(TimeSpan) timeout (the default for this is 5 seconds). This could happen due to a network problem or a temporary service outage. In this case, Initialized will be false, and the DataSourceStatusProvider will return a state of Initializing, indicating that the SDK will still continue trying to connect in the background.
3. It has encountered an unrecoverable error: for instance, LaunchDarkly has rejected the SDK key. Since an invalid key will not become valid, the SDK will not retry in this case. Initialized will be false, and the DataSourceStatusProvider will return a state of Off.

If you have specified Offline(bool) mode or ExternalUpdatesOnly, the constructor returns immediately without trying to connect to LaunchDarkly.

Failure to connect to LaunchDarkly will never cause the constructor to throw an exception. Under any circumstance where it is not able to get feature flag data from LaunchDarkly (and therefore Initialized is false), if it does not have any other source of data (such as a persistent data store) then feature flag evaluations will behave the same as if the flags were not found: that is, they will return whatever default value is specified in your code.

Examples

var config = Configuration.Builder("my-sdk-key").Build();
var client = new LDClient(config);

See Also

LdClient(string)

LdClient(string)

Creates a new client instance that connects to LaunchDarkly with the default configuration.

Declaration

public LdClient(string sdkKey)

Parameters

Type	Name	Description
string	sdkKey	the SDK key for your LaunchDarkly environment

Remarks

If you need to specify any custom SDK options, use LdClient(Configuration) instead.

Applications should instantiate a single instance for the lifetime of the application. In unusual cases where an application needs to evaluate feature flags from different LaunchDarkly projects or environments, you may create multiple clients, but they should still be retained for the lifetime of the application rather than created per request or per thread.

The constructor will never throw an exception, even if initialization fails. For more details about initialization behavior and how to detect error conditions, see LdClient(Configuration).

See Also

LdClient(Configuration)

Properties

BigSegmentStoreStatusProvider

A mechanism for tracking the status of a Big Segment store.

Declaration

public IBigSegmentStoreStatusProvider BigSegmentStoreStatusProvider { get; }

Property Value

Type	Description
IBigSegmentStoreStatusProvider

Remarks

The returned object has methods for checking whether the Big Segment store is (as far as the SDK knows) currently operational and tracking changes in this status. See IBigSegmentStoreStatusProvider for more about this functionality.

DataSourceStatusProvider

A mechanism for tracking the status of the data source.

Declaration

public IDataSourceStatusProvider DataSourceStatusProvider { get; }

Property Value

Type	Description
IDataSourceStatusProvider

Remarks

The data source is the mechanism that the SDK uses to get feature flag configurations, such as a streaming connection (the default) or poll requests. The IDataSourceStatusProvider has methods for checking whether the data source is (as far as the SDK knows) currently operational, and tracking changes in this status. This property will never be null.

DataStoreStatusProvider

A mechanism for tracking the status of a persistent data store.

Declaration

public IDataStoreStatusProvider DataStoreStatusProvider { get; }

Property Value

Type	Description
IDataStoreStatusProvider

Remarks

The IDataStoreStatusProvider has methods for checking whether the data store is (as far as the SDK knows) currently operational and tracking changes in this status. These are only relevant for a persistent data store; if you are using an in-memory data store, then this property is a stub object that always reports the store as operational.

FlagTracker

A mechanism for tracking changes in feature flag configurations.

Declaration

public IFlagTracker FlagTracker { get; }

Property Value

Type	Description
IFlagTracker

Remarks

The IFlagTracker contains methods for requesting notifications about feature flag changes using an event listener model.

Initialized

Tests whether the client is ready to be used.

Declaration

public bool Initialized { get; }

Property Value

Type	Description
bool	true if the client is ready, or false if it is still initializing

Version

Declaration

public Version Version { get; }

Property Value

Type	Description
Version

Methods

AllFlagsState(Context, params FlagsStateOption[])

Returns an object that encapsulates the state of all feature flags for a given context, which can be passed to front-end code.

Declaration

public FeatureFlagsState AllFlagsState(Context context, params FlagsStateOption[] options)

Parameters

Type	Name	Description
Context	context	the evaluation context
FlagsStateOption[]	options	optional FlagsStateOption values affecting how the state is computed-- for instance, to filter the set of flags to only include the client-side-enabled ones

Returns

Type	Description
FeatureFlagsState	a FeatureFlagsState object (will never be null; see Valid

Remarks

The object returned by this method contains the flag values as well as other metadata that is used by the LaunchDarkly JavaScript client, so it can be used for bootstrapping.

This method will not send analytics events back to LaunchDarkly.

BoolVariation(string, Context, bool)

Calculates the boolean value of a feature flag for a given context.

Declaration

public bool BoolVariation(string key, Context context, bool defaultValue = false)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
bool	defaultValue	the default value of the flag

Returns

Type	Description
bool	the variation for the given context, or defaultValue if the flag cannot be evaluated

Remarks

If the flag variation does not have a boolean value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

See Also

BoolVariationDetail(string, Context, bool)

BoolVariationDetail(string, Context, bool)

Calculates the boolean value of a feature flag for a given context, and returns an object that describes the way the value was determined.

Declaration

public EvaluationDetail<bool> BoolVariationDetail(string key, Context context, bool defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
bool	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<bool>	an EvaluationDetail<T> object

Remarks

The Reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to BoolVariation(string, Context, bool).

See Also

BoolVariation(string, Context, bool)

Dispose()

Shuts down the client and releases any resources it is using.

Declaration

public void Dispose()

Remarks

Unless it is offline, the client will attempt to deliver any pending analytics events before closing.

Any components that were added by specifying a factory object (DataStore(IComponentConfigurer<IDataStore>), etc.) will also be disposed of by this method; their lifecycle is the same as the client's.

DoubleVariation(string, Context, double)

Calculates the double-precision floating-point numeric value of a feature flag for a given context.

Declaration

public double DoubleVariation(string key, Context context, double defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
double	defaultValue	the default value of the flag

Returns

Type	Description
double	the variation for the given context, or defaultValue if the flag cannot be evaluated

Remarks

If the flag variation does not have a numeric value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

See Also

DoubleVariationDetail(string, Context, double)

FloatVariation(string, Context, float)

DoubleVariationDetail(string, Context, double)

Calculates the double-precision floating-point numeric value of a feature flag for a given context, and returns an object that describes the way the value was determined.

Declaration

public EvaluationDetail<double> DoubleVariationDetail(string key, Context context, double defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
double	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<double>	an EvaluationDetail<T> object

Remarks

The Reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to DoubleVariation(string, Context, double).

See Also

DoubleVariation(string, Context, double)

FloatVariationDetail(string, Context, float)

FloatVariation(string, Context, float)

Calculates the single-precision floating-point numeric value of a feature flag for a given context.

Declaration

public float FloatVariation(string key, Context context, float defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
float	defaultValue	the default value of the flag

Returns

Type	Description
float	the variation for the given context, or defaultValue if the flag cannot be evaluated

Remarks

If the flag variation does not have a numeric value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

See Also

FloatVariationDetail(string, Context, float)

DoubleVariation(string, Context, double)

FloatVariationDetail(string, Context, float)

Calculates the single-precision floating-point numeric value of a feature flag for a given context, and returns an object that describes the way the value was determined.

Declaration

public EvaluationDetail<float> FloatVariationDetail(string key, Context context, float defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
float	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<float>	an EvaluationDetail<T> object

Remarks

The Reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to FloatVariation(string, Context, float).

See Also

FloatVariation(string, Context, float)

DoubleVariationDetail(string, Context, double)

Flush()

Tells the client that all pending analytics events (if any) should be delivered as soon as possible.

Declaration

public void Flush()

Remarks

This flush is asynchronous, so this method will return before it is complete. To wait for the flush to complete, use FlushAndWait(TimeSpan) instead (or, if you are done with the SDK, Dispose()).

For more information, see: Flushing Events.

See Also

FlushAndWait(TimeSpan)

FlushAndWait(TimeSpan)

Tells the client to deliver any pending analytics events synchronously now.

Declaration

public bool FlushAndWait(TimeSpan timeout)

Parameters

Type	Name	Description
TimeSpan	timeout	the maximum time to wait

Returns

Type	Description
bool	true if completed, false if timed out

Remarks

Unlike Flush(), this method waits for event delivery to finish. The timeout parameter, if greater than zero, specifies the maximum amount of time to wait. If the timeout elapses before delivery is finished, the method returns early and returns false; in this case, the SDK may still continue trying to deliver the events in the background.

If the timeout parameter is zero or negative, the method waits as long as necessary to deliver the events. However, the SDK does not retry event delivery indefinitely; currently, any network error or server error will cause the SDK to wait one second and retry one time, after which the events will be discarded so that the SDK will not keep consuming more memory for events indefinitely.

The method returns true if event delivery either succeeded, or definitively failed, before the timeout elapsed. It returns false if the timeout elapsed.

This method is also implicitly called if you call Dispose(). The difference is that FlushAndWait does not shut down the SDK client.

For more information, see: Flushing Events.

See Also

Flush()

GetLogger()

Returns the logger instance used by this SDK instance.

Declaration

public Logger GetLogger()

Returns

Type	Description
Logger	the logger instance used by the SDK

Remarks

This allows for access to the logger by other LaunchDarkly components, such as the Migration class.

It also allows for usage of the logger in wrapper implementations.

It is not intended for general purpose application logging.

Identify(Context)

Reports details about an evaluation context.

Declaration

public void Identify(Context context)

Parameters

Type	Name	Description
Context	context	the evaluation context

Remarks

This method simply creates an analytics event containing the context attributes, to that LaunchDarkly will know about that context if it does not already.

Calling any evaluation method, such as BoolVariation(string, Context, bool), also sends the context information to LaunchDarkly (if events are enabled), so you only need to use Identify(Context) if you want to identify the context without evaluating a flag.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see Flush().

For more information, see the Reference Guide.

IntVariation(string, Context, int)

Calculates the integer value of a feature flag for a given context.

Declaration

public int IntVariation(string key, Context context, int defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
int	defaultValue	the default value of the flag

Returns

Type	Description
int	the variation for the given context, or defaultValue if the flag cannot be evaluated

Remarks

If the flag variation has a numeric value that is not an integer, it is rounded to the nearest integer. This rounding behavior may be changed in a future version of the SDK (for instance, to round toward zero like the usual float-to-int conversion in C#), so you should avoid relying on it.

If the flag variation does not have a numeric value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

See Also

IntVariationDetail(string, Context, int)

IntVariationDetail(string, Context, int)

Calculates the integer value of a feature flag for a given context, and returns an object that describes the way the value was determined.

Declaration

public EvaluationDetail<int> IntVariationDetail(string key, Context context, int defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
int	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<int>	an EvaluationDetail<T> object

Remarks

The Reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to IntVariation(string, Context, int).

See Also

IntVariation(string, Context, int)

IsOffline()

Returns true if the client has been configured to be offline.

Declaration

public bool IsOffline()

Returns

Type	Description
bool	true if the client is configured to be offline

Remarks

This value will be static for the execution of a client. If you want active data source status for an online client, then use DataSourceStatusProvider.

JsonVariation(string, Context, LdValue)

Calculates the value of a feature flag for a given context as any JSON value type.

Declaration

public LdValue JsonVariation(string key, Context context, LdValue defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
LdValue	defaultValue	the default value of the flag

Returns

Type	Description
LdValue	the variation for the given context, or defaultValue if the flag cannot be evaluated

Remarks

The type LdValue is used to represent any of the value types that can exist in JSON. Use LdValue methods to examine its type and value.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

See Also

JsonVariationDetail(string, Context, LdValue)

JsonVariationDetail(string, Context, LdValue)

Calculates the value of a feature flag for a given context as any JSON value type, and returns an object that describes the way the value was determined.

Declaration

public EvaluationDetail<LdValue> JsonVariationDetail(string key, Context context, LdValue defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
LdValue	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<LdValue>	an EvaluationDetail<T> object

Remarks

The Reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to JsonVariationDetail(string, Context, LdValue).

See Also

JsonVariation(string, Context, LdValue)

MigrationVariation(string, Context, MigrationStage)

Returns the migration stage of the migration feature flag for the given evaluation context.

Declaration

public MigrationVariation MigrationVariation(string key, Context context, MigrationStage defaultStage)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
MigrationStage	defaultStage	the default value of the flag

Returns

Type	Description
MigrationVariation	an MigrationVariation(string, Context, MigrationStage) object

SecureModeHash(Context)

Creates a hash string that can be used by the JavaScript SDK to identify a context.

Declaration

public string SecureModeHash(Context context)

Parameters

Type	Name	Description
Context	context	the evaluation context

Returns

Type	Description
string	the hash, or null if the hash could not be calculated

Remarks

See Secure mode in the JavaScript SDK Reference.

StringVariation(string, Context, string)

Calculates the string value of a feature flag for a given context.

Declaration

public string StringVariation(string key, Context context, string defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
string	defaultValue	the default value of the flag

Returns

Type	Description
string	the variation for the given context, or defaultValue if the flag cannot be evaluated

Remarks

If the flag variation does not have a string value, defaultValue is returned.

Normally, the string value of a flag should not be null, since the LaunchDarkly UI does not allow you to assign a null value to a flag variation. However, since it may be possible to create a feature flag with a null variation by other means, and also since defaultValue is nullable, you should assume that the return value might be null.

See Also

StringVariationDetail(string, Context, string)

StringVariationDetail(string, Context, string)

Calculates the string value of a feature flag for a given context, and returns an object that describes the way the value was determined.

Declaration

public EvaluationDetail<string> StringVariationDetail(string key, Context context, string defaultValue)

Parameters

Type	Name	Description
string	key	the unique feature key for the feature flag
Context	context	the evaluation context
string	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<string>	an EvaluationDetail<T> object

Remarks

The Reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to StringVariation(string, Context, string).

See Also

StringVariation(string, Context, string)

Track(string, Context)

Tracks that an application-defined event occurred.

Declaration

public void Track(string name, Context context)

Parameters

Type	Name	Description
string	name	the name of the event
Context	context	the evaluation context associated with the event

Remarks

This method creates a "custom" analytics event containing the specified event name (key) and context attributes. You may attach arbitrary data to the event by calling Track(string, Context, LdValue) instead.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see Flush().

See Also

Track(string, Context, LdValue)

Track(string, Context, LdValue, double)

Track(string, Context, LdValue)

Tracks that an application-defined event occurred.

Declaration

public void Track(string name, Context context, LdValue data)

Parameters

Type	Name	Description
string	name	the name of the event
Context	context	the evaluation context associated with the event
LdValue	data	additional data associated with the event, if any

Remarks

This method creates a "custom" analytics event containing the specified event name (key), context properties, and optional custom data. If you do not need custom data, pass Null for the last parameter or simply omit the parameter.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see Flush().

See Also

Track(string, Context)

Track(string, Context, LdValue, double)

Track(string, Context, LdValue)

Track(string, Context, LdValue, double)

Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.

Declaration

public void Track(string name, Context context, LdValue data, double metricValue)

Parameters

Type	Name	Description
string	name	the name of the event
Context	context	the evaluation context associated with the event
LdValue	data	additional data associated with the event; use Null if not applicable
double	metricValue	a numeric value used by the LaunchDarkly experimentation feature in numeric custom metrics

Remarks

This value is used by the LaunchDarkly experimentation feature in numeric custom metrics, and will also be returned as part of the custom event for Data Export.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see Flush().

See Also

Track(string, Context)

Track(string, Context, LdValue)

TrackMigration(MigrationOpTracker)

Track the details of a migration.

Declaration

public void TrackMigration(MigrationOpTracker tracker)

Parameters

Type	Name	Description
MigrationOpTracker	tracker	migration tracker which was used to track the details of a migration

Implements

IDisposable

ILdClient

Extension Methods

ILdClientExtensions.EnumVariationDetail<T>(ILdClient, string, Context, T)

ILdClientExtensions.EnumVariation<T>(ILdClient, string, Context, T)