Interface ILdClient

Interface for the standard SDK client methods and properties. The only implementation of this is LdClient.

Inherited Members

IDisposable.Dispose()

Namespace: LaunchDarkly.Sdk.Client.Interfaces

Assembly: LaunchDarkly.ClientSdk.dll

Syntax

public interface ILdClient : IDisposable

Remarks

See also ILdClientExtensions, which provides convenience methods that build upon this interface.

Properties

DataSourceStatusProvider

A mechanism for tracking the status of the data source.

Declaration

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.

FlagTracker

A mechanism for tracking changes in feature flag configurations.

Declaration

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

Returns a boolean value indicating LaunchDarkly connection and flag state within the client.

Declaration

bool Initialized { get; }

Property Value

Type	Description
bool

Remarks

When you first start the client, once Init(Configuration, Context, TimeSpan) or InitAsync(Configuration, Context) has returned, Initialized should be true if and only if either 1. it connected to LaunchDarkly and successfully retrieved flags, or 2. it started in offline mode so there's no need to connect to LaunchDarkly. If the client timed out trying to connect to LD, then Initialized is false (even if we do have cached flags). If the client connected and got a 401 error, Initialized is false. This serves the purpose of letting the app know that there was a problem of some kind.

If you call Identify(Context, TimeSpan) or IdentifyAsync(Context), Initialized will become false until the SDK receives the new context's flags.

Offline

Indicates whether the SDK is configured to be always offline.

Declaration

bool Offline { get; }

Property Value

Type	Description
bool

Remarks

This is initially true if you set it to true in the configuration with Offline(bool). However, you can change it at any time to allow the client to go online, or force it to go offline, using SetOffline(bool, TimeSpan) or SetOfflineAsync(bool).

When Offline is false, the SDK connects to LaunchDarkly if possible, but this does not guarantee that the connection is successful. There is currently no mechanism to detect whether the SDK is currently connected to LaunchDarkly.

Methods

AllFlags()

Returns a map from feature flag keys to LdValue feature flag values for the current user.

Declaration

IDictionary<string, LdValue> AllFlags()

Returns

Type	Description
IDictionary<string, LdValue>	a map from feature flag keys to values for the current user

Remarks

If the result of a flag's value would have returned the default variation, the value in the map will contain Null. If the client is offline or has not been initialized, an empty map will be returned.

This method will not send analytics events back to LaunchDarkly.

BoolVariation(string, bool)

Returns the boolean value of a feature flag for a given flag key.

Declaration

bool BoolVariation(string key, bool defaultValue = false)

Parameters

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

Returns

Type	Description
bool	the variation for the selected user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

BoolVariationDetail(string, bool)

Returns the boolean value of a feature flag for a given flag key, in an object that also describes the way the value was determined.

Declaration

EvaluationDetail<bool> BoolVariationDetail(string key, bool defaultValue = false)

Parameters

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

Returns

Type	Description
EvaluationDetail<bool>	an EvaluationDetail 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.

DoubleVariation(string, double)

Returns the double-precision floating-point value of a feature flag for a given flag key.

Declaration

double DoubleVariation(string key, double defaultValue = 0)

Parameters

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

Returns

Type	Description
double	the variation for the selected user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

DoubleVariationDetail(string, double)

Returns the double-precision floating-point value of a feature flag for a given flag key, in an object that also describes the way the value was determined.

Declaration

EvaluationDetail<double> DoubleVariationDetail(string key, double defaultValue = 0)

Parameters

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

Returns

Type	Description
EvaluationDetail<double>	an EvaluationDetail 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.

FloatVariation(string, float)

Returns the single-precision floating-point value of a feature flag for a given flag key.

Declaration

float FloatVariation(string key, float defaultValue = 0)

Parameters

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

Returns

Type	Description
float	the variation for the selected user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

FloatVariationDetail(string, float)

Returns the single-precision floating-point value of a feature flag for a given flag key, in an object that also describes the way the value was determined.

Declaration

EvaluationDetail<float> FloatVariationDetail(string key, float defaultValue = 0)

Parameters

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

Returns

Type	Description
EvaluationDetail<float>	an EvaluationDetail 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.

Flush()

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

Declaration

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)

FlushAndWaitAsync(TimeSpan)

FlushAndWait(TimeSpan)

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

Declaration

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

FlushAndWaitAsync(TimeSpan)

FlushAndWaitAsync(TimeSpan)

Tells the client to deliver any pending analytics events now, returning a Task that can be awaited.

Declaration

Task<bool> FlushAndWaitAsync(TimeSpan timeout)

Parameters

Type	Name	Description
TimeSpan	timeout	the maximum time to wait

Returns

Type	Description
Task<bool>	a Task that resolves to true if completed, false if timed out

Remarks

This is equivalent to FlushAndWait(TimeSpan), but with asynchronous semantics so it does not block the calling thread. The difference between this and Flush() is that you can await the task to simulate blocking behavior.

For more information, see: Flushing Events.

See Also

Flush()

FlushAndWait(TimeSpan)

Identify(Context, TimeSpan)

Changes the current evaluation context, requests flags for that context from LaunchDarkly if we are online, and generates an analytics event to tell LaunchDarkly about the context.

Declaration

bool Identify(Context context, TimeSpan maxWaitTime)

Parameters

Type	Name	Description
Context	context	the new evaluation context; see LdClient for more about setting the context and optionally requesting a unique key for it
TimeSpan	maxWaitTime	the maximum time to wait for the new flag values

Returns

Type	Description
bool	true if new flag values were obtained

Remarks

This is equivalent to IdentifyAsync(Context), but as a synchronous method.

If the SDK is online, Identify(Context, TimeSpan) waits to receive feature flag values for the new context from LaunchDarkly. If it receives the new flag values before maxWaitTime has elapsed, it returns true. If the timeout elapses, it returns false (although the SDK might still receive the flag values later). If we do not need to request flags from LaunchDarkly because we are in offline mode, it returns true.

If you do not want to wait, you can either set maxWaitTime to zero or call IdentifyAsync(Context).

See Also

IdentifyAsync(Context)

IdentifyAsync(Context)

Changes the current evaluation context, requests flags for that context from LaunchDarkly if we are online, and generates an analytics event to tell LaunchDarkly about the context.

Declaration

Task<bool> IdentifyAsync(Context context)

Parameters

Type	Name	Description
Context	context	the new evaluation context; see LdClient for more about setting the context and optionally requesting a unique key for it

Returns

Type	Description
Task<bool>	a task that yields true if new flag values were obtained

Remarks

This is equivalent to Identify(Context, TimeSpan), but as an asynchronous method.

If the SDK is online, the returned task is completed once the SDK has received feature flag values for the new user from LaunchDarkly, or received an unrecoverable error; it yields true for success or false for an error. If the SDK is offline, the returned task is completed immediately and yields true.

See Also

Identify(Context, TimeSpan)

IntVariation(string, int)

Returns the integer value of a feature flag for a given flag key.

Declaration

int IntVariation(string key, int defaultValue = 0)

Parameters

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

Returns

Type	Description
int	the variation for the selected user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

IntVariationDetail(string, int)

Returns the integer value of a feature flag for a given flag key, in an object that also describes the way the value was determined.

Declaration

EvaluationDetail<int> IntVariationDetail(string key, int defaultValue = 0)

Parameters

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

Returns

Type	Description
EvaluationDetail<int>	an EvaluationDetail 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.

JsonVariation(string, LdValue)

Returns the JSON value of a feature flag for a given flag key.

Declaration

LdValue JsonVariation(string key, LdValue defaultValue)

Parameters

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

Returns

Type	Description
LdValue	the variation for the selected user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

JsonVariationDetail(string, LdValue)

Returns the JSON value of a feature flag for a given flag key, in an object that also describes the way the value was determined.

Declaration

EvaluationDetail<LdValue> JsonVariationDetail(string key, LdValue defaultValue)

Parameters

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

Returns

Type	Description
EvaluationDetail<LdValue>	an EvaluationDetail 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.

SetOffline(bool, TimeSpan)

Sets whether the SDK should be always offline.

Declaration

bool SetOffline(bool value, TimeSpan maxWaitTime)

Parameters

Type	Name	Description
bool	value	true if the client should be always offline
TimeSpan	maxWaitTime	the maximum length of time to wait for a connection

Returns

Type	Description
bool	true if a new connection was successfully made

Remarks

This is equivalent to SetOfflineAsync(bool), but as a synchronous method.

If you set the property to true, any existing connection will be dropped, and the method immediately returns false.

If you set it to false when it was previously true, but no connection can be made because the network is not available, the method immediately returns false, but the SDK will attempt to connect later if the network becomes available.

If you set it to false when it was previously true, and the network is available, the SDK will attempt to connect to LaunchDarkly. If the connection succeeds within the interval maxWaitTime, the method returns true. If the connection permanently fails (e.g. if the mobile key is invalid), the method returns false. If the connection attempt is still in progress after maxWaitTime elapses, the method returns false, but the connection might succeed later.

SetOfflineAsync(bool)

Sets whether the SDK should be always offline.

Declaration

Task SetOfflineAsync(bool value)

Parameters

Type	Name	Description
bool	value	true if the client should be always offline

Returns

Type	Description
Task	a task that yields true if a new connection was successfully made

Remarks

This is equivalent to SetOffline(bool, TimeSpan), but as an asynchronous method.

If you set the property to true, any existing connection will be dropped, and the task immediately yields false.

If you set it to false when it was previously true, but no connection can be made because the network is not available, the task immediately yields false, but the SDK will attempt to connect later if the network becomes available.

If you set it to false when it was previously true, and the network is available, the SDK will attempt to connect to LaunchDarkly. If and when the connection succeeds, the task yields true. If and when the connection permanently fails (e.g. if the mobile key is invalid), the task yields false.

StringVariation(string, string)

Returns the string value of a feature flag for a given flag key.

Declaration

string StringVariation(string key, string defaultValue)

Parameters

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

Returns

Type	Description
string	the variation for the selected user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

StringVariationDetail(string, string)

Returns the string value of a feature flag for a given flag key, in an object that also describes the way the value was determined.

Declaration

EvaluationDetail<string> StringVariationDetail(string key, string defaultValue)

Parameters

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

Returns

Type	Description
EvaluationDetail<string>	an EvaluationDetail 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.

Track(string)

Tracks that current user performed an event for the given event name.

Declaration

void Track(string eventName)

Parameters

Type	Name	Description
string	eventName	the name of the event

Track(string, LdValue)

Tracks that the current user performed an event for the given event name, with additional JSON data.

Declaration

void Track(string eventName, LdValue data)

Parameters

Type	Name	Description
string	eventName	the name of the event
LdValue	data	a JSON value containing additional data associated with the event

Track(string, LdValue, double)

Tracks that the current user performed an event for the given event name, and associates it with a numeric metric value.

Declaration

void Track(string eventName, LdValue data, double metricValue)

Parameters

Type	Name	Description
string	eventName	the name of the event
LdValue	data	a JSON value containing additional data associated with the event; pass Null if you do not need this value
double	metricValue	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

Extension Methods

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

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

ILdClientExtensions.Identify(ILdClient, User, TimeSpan)

ILdClientExtensions.IdentifyAsync(ILdClient, User)