Class LdClient

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

Inheritance

System.Object

LdClient

Implements

ILdClient

System.IDisposable

Namespace: LaunchDarkly.Sdk.Client

Assembly: LaunchDarkly.ClientSdk.dll

Syntax

public sealed class LdClient : Object, ILdClient, IDisposable

Remarks

Like all client-side LaunchDarkly SDKs, the LdClient always has a single current Context. You specify this context at initialization time, and you can change it later with Identify(Context, TimeSpan) or IdentifyAsync(Context). All subsequent calls to evaluation methods like BoolVariation(String, Boolean) refer to the flag values for the current context.

Normally, the SDK uses the exact context that you have specified in the Context. However, you can also tell the SDK to generate a randomized identifier and use this as the context's Key; see GenerateAnonymousKeys(Boolean).

If you use more than one ContextKind in your evaluation contexts, and you request a randomized key as described above, a different key is generated for each kind.

Properties

Config

The Configuration instance used to set up the LdClient.

Declaration

public Configuration Config { get; }

Property Value

Type	Description
Configuration

Context

The current evaluation context for all SDK operations.

Declaration

public Context Context { get; }

Property Value

Type	Description
Context

Remarks

This is initially the context specified for Init(Configuration, Context, TimeSpan) or InitAsync(Configuration, Context), but can be changed later with Identify(Context, TimeSpan) or IdentifyAsync(Context).

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.

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

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

Declaration

public bool Initialized { get; }

Property Value

Type	Description
System.Boolean

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.

Instance

The singleton instance used by your application throughout its lifetime. Once this exists, you cannot create a new client instance unless you first call Dispose() on this one.

Declaration

public static LdClient Instance { get; }

Property Value

Type	Description
LdClient

Remarks

Use the static factory methods Init(Configuration, Context, TimeSpan) or InitAsync(Configuration, Context) to set this LdClient instance.

Offline

Indicates whether the SDK is configured to be always offline.

Declaration

public bool Offline { get; }

Property Value

Type	Description
System.Boolean

Remarks

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

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.

PlatformType

Indicates which platform the SDK is built for.

Declaration

public static PlatformType PlatformType { get; }

Property Value

Type	Description
PlatformType

Remarks

This property is mainly useful for debugging. It does not indicate which platform you are actually running on, but rather which variant of the SDK is currently in use.

The LaunchDarkly.ClientSdk package contains assemblies for multiple target platforms. In an Android or iOS application, you will normally be using the Android or iOS variant of the SDK; that is done automatically when you install the NuGet package. On all other platforms, you will get the .NET Standard variant.

The basic features of the SDK are the same in all of these variants; the difference is in platform-specific behavior such as detecting when an application has gone into the background, detecting network connectivity, and ensuring that code is executed on the UI thread if applicable for that platform. Therefore, if you find that these platform-specific behaviors are not working correctly, you may want to check this property to make sure you are not for some reason running the .NET Standard SDK on a phone.

Version

The current version string of the SDK.

Declaration

public static Version Version { get; }

Property Value

Type	Description
System.Version

Methods

AllFlags()

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

Declaration

public IDictionary<string, LdValue> AllFlags()

Returns

Type	Description
System.Collections.Generic.IDictionary<System.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, Boolean)

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

Declaration

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

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Boolean	defaultValue	the default value of the flag

Returns

Type	Description
System.Boolean	the variation for the selected user, or `defaultValue` if the flag is disabled in the LaunchDarkly control panel

BoolVariationDetail(String, Boolean)

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

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

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Boolean	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<System.Boolean>	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.

Dispose()

Permanently shuts down the SDK client.

Declaration

public void Dispose()

Remarks

This method closes all network collections, shuts down all background tasks, and releases any other resources being held by the SDK.

If there are any pending analytics events, and if the SDK is online, it attempts to deliver the events to LaunchDarkly before closing.

DoubleVariation(String, Double)

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

Declaration

public double DoubleVariation(string key, double defaultValue = 0)

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Double	defaultValue	the default value of the flag

Returns

Type	Description
System.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

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

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Double	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<System.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, Single)

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

Declaration

public float FloatVariation(string key, float defaultValue = 0F)

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Single	defaultValue	the default value of the flag

Returns

Type	Description
System.Single	the variation for the selected user, or `defaultValue` if the flag is disabled in the LaunchDarkly control panel

FloatVariationDetail(String, Single)

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

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

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Single	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<System.Single>	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

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.

FlushAndWait(TimeSpan)

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

Declaration

public bool FlushAndWait(TimeSpan timeout)

Parameters

Type	Name	Description
System.TimeSpan	timeout	the maximum time to wait

Returns

Type	Description
System.Boolean	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.

FlushAndWaitAsync(TimeSpan)

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

Declaration

public Task<bool> FlushAndWaitAsync(TimeSpan timeout)

Parameters

Type	Name	Description
System.TimeSpan	timeout	the maximum time to wait

Returns

Type	Description
System.Threading.Tasks.Task<System.Boolean>	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.

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

public 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
System.TimeSpan	maxWaitTime	the maximum time to wait for the new flag values

Returns

Type	Description
System.Boolean	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).

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

public 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
System.Threading.Tasks.Task<System.Boolean>	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.

Init(Configuration, Context, TimeSpan)

Creates and returns a new LdClient singleton instance, then starts the workflow for fetching Feature Flags.

Declaration

public static LdClient Init(Configuration config, Context initialContext, TimeSpan maxWaitTime)

Parameters

Type	Name	Description
Configuration	config	the client configuration
Context	initialContext	the initial evaluation context; see LdClient for more about setting the context and optionally requesting a unique key for it
System.TimeSpan	maxWaitTime	the maximum length of time to wait for the client to initialize; if this time elapses, the method will not throw an exception but will return the client in an uninitialized state

Returns

Type	Description
LdClient	the singleton LdClient instance

Remarks

In offline mode, this constructor will return immediately. Otherwise, it will wait and block on the current thread until initialization and the first response from the LaunchDarkly service is returned, up to the specified timeout. If the timeout elapses, the returned instance will have an Initialized property of false.

If you would rather this happen asynchronously, use InitAsync(Configuration, Context). If you do not need to specify configuration options other than the mobile key, you can use Init(String, Context, TimeSpan) or InitAsync(String, Context).

You must use one of these static factory methods to instantiate the single instance of LdClient for the lifetime of your application.

Init(Configuration, User, TimeSpan)

Creates and returns a new LdClient singleton instance, then starts the workflow for fetching Feature Flags.

Declaration

public static LdClient Init(Configuration config, User initialUser, TimeSpan maxWaitTime)

Parameters

Type	Name	Description
Configuration	config	the client configuration
User	initialUser	the initial user attributes
System.TimeSpan	maxWaitTime	the maximum length of time to wait for the client to initialize; if this time elapses, the method will not throw an exception but will return the client in an uninitialized state

Returns

Type	Description
LdClient	the singleton LdClient instance

Remarks

This is equivalent to Init(Configuration, Context, TimeSpan), but using the User type instead of Context.

Init(String, Context, TimeSpan)

Creates a new LdClient singleton instance and attempts to initialize feature flags.

Declaration

public static LdClient Init(string mobileKey, Context initialContext, TimeSpan maxWaitTime)

Parameters

Type	Name	Description
System.String	mobileKey	the mobile key given to you by LaunchDarkly
Context	initialContext	the initial evaluation context; see LdClient for more about setting the context and optionally requesting a unique key for it
System.TimeSpan	maxWaitTime	the maximum length of time to wait for the client to initialize

Returns

Type	Description
LdClient	the singleton LdClient instance

Remarks

If you would rather this happen asynchronously, use InitAsync(String, Context). To specify additional configuration options rather than just the mobile key, use Init(Configuration, Context, TimeSpan) or InitAsync(Configuration, Context).

You must use one of these static factory methods to instantiate the single instance of LdClient for the lifetime of your application.

Init(String, User, TimeSpan)

Creates a new LdClient singleton instance and attempts to initialize feature flags.

Declaration

public static LdClient Init(string mobileKey, User initialUser, TimeSpan maxWaitTime)

Parameters

Type	Name	Description
System.String	mobileKey	the mobile key given to you by LaunchDarkly
User	initialUser	the initial user attributes; see LdClient for more about setting the context and optionally requesting a unique key for it
System.TimeSpan	maxWaitTime	the maximum length of time to wait for the client to initialize

Returns

Type	Description
LdClient	the singleton LdClient instance

Remarks

This is equivalent to Init(String, Context, TimeSpan), but using the User type instead of Context.

InitAsync(Configuration, Context)

Creates a new LdClient singleton instance and attempts to initialize feature flags asynchronously.

Declaration

public static Task<LdClient> InitAsync(Configuration config, Context initialContext)

Parameters

Type	Name	Description
Configuration	config	the client configuration
Context	initialContext	the initial evaluation context; see LdClient for more about setting the context and optionally requesting a unique key for it

Returns

Type	Description
System.Threading.Tasks.Task<LdClient>	a Task that resolves to the singleton LdClient instance

Remarks

The returned task will yield the LdClient instance once the first response from the LaunchDarkly service is returned (or immediately if it is in offline mode).

If you would rather this happen synchronously, use Init(Configuration, Context, TimeSpan). If you do not need to specify configuration options other than the mobile key, you can use Init(String, Context, TimeSpan) or InitAsync(String, Context).

You must use one of these static factory methods to instantiate the single instance of LdClient for the lifetime of your application.

InitAsync(Configuration, User)

Creates a new LdClient singleton instance and attempts to initialize feature flags asynchronously.

Declaration

public static Task<LdClient> InitAsync(Configuration config, User initialUser)

Parameters

Type	Name	Description
Configuration	config	the client configuration
User	initialUser	the initial user attributes

Returns

Type	Description
System.Threading.Tasks.Task<LdClient>	a Task that resolves to the singleton LdClient instance

Remarks

This is equivalent to InitAsync(Configuration, Context), but using the User type instead of Context.

InitAsync(String, Context)

Creates a new LdClient singleton instance and attempts to initialize feature flags asynchronously.

Declaration

public static Task<LdClient> InitAsync(string mobileKey, Context initialContext)

Parameters

Type	Name	Description
System.String	mobileKey	the mobile key given to you by LaunchDarkly
Context	initialContext	the initial evaluation context; see LdClient for more about setting the context and optionally requesting a unique key for it

Returns

Type	Description
System.Threading.Tasks.Task<LdClient>	a Task that resolves to the singleton LdClient instance

Remarks

The returned task will yield the LdClient instance once the first response from the LaunchDarkly service is returned (or immediately if it is in offline mode).

If you would rather this happen synchronously, use Init(String, Context, TimeSpan). To specify additional configuration options rather than just the mobile key, you can use Init(Configuration, Context, TimeSpan) or InitAsync(Configuration, Context).

You must use one of these static factory methods to instantiate the single instance of LdClient for the lifetime of your application.

InitAsync(String, User)

Creates a new LdClient singleton instance and attempts to initialize feature flags asynchronously.

Declaration

public static Task<LdClient> InitAsync(string mobileKey, User initialUser)

Parameters

Type	Name	Description
System.String	mobileKey	the mobile key given to you by LaunchDarkly
User	initialUser	the initial user attributes

Returns

Type	Description
System.Threading.Tasks.Task<LdClient>	a Task that resolves to the singleton LdClient instance

Remarks

This is equivalent to InitAsync(String, Context), but using the User type instead of Context.

IntVariation(String, Int32)

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

Declaration

public int IntVariation(string key, int defaultValue = 0)

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Int32	defaultValue	the default value of the flag

Returns

Type	Description
System.Int32	the variation for the selected user, or `defaultValue` if the flag is disabled in the LaunchDarkly control panel

IntVariationDetail(String, Int32)

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

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

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.Int32	defaultValue	the default value of the flag

Returns

Type	Description
EvaluationDetail<System.Int32>	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

public LdValue JsonVariation(string key, LdValue defaultValue)

Parameters

Type	Name	Description
System.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

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

Parameters

Type	Name	Description
System.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(Boolean, TimeSpan)

Sets whether the SDK should be always offline.

Declaration

public bool SetOffline(bool value, TimeSpan maxWaitTime)

Parameters

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

Returns

Type	Description
System.Boolean	true if a new connection was successfully made

Remarks

This is equivalent to SetOfflineAsync(Boolean), 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(Boolean)

Sets whether the SDK should be always offline.

Declaration

public Task SetOfflineAsync(bool value)

Parameters

Type	Name	Description
System.Boolean	value	true if the client should be always offline

Returns

Type	Description
System.Threading.Tasks.Task	a task that yields true if a new connection was successfully made

Remarks

This is equivalent to SetOffline(Boolean, 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

public string StringVariation(string key, string defaultValue)

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.String	defaultValue	the default value of the flag

Returns

Type	Description
System.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

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

Parameters

Type	Name	Description
System.String	key	the unique feature key for the feature flag
System.String	defaultValue	the default value of the flag

Returns

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

public void Track(string eventName)

Parameters

Type	Name	Description
System.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

public void Track(string eventName, LdValue data)

Parameters

Type	Name	Description
System.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

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

Parameters

Type	Name	Description
System.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
System.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

Implements

ILdClient

System.IDisposable