Class ContextBuilder

A mutable object that uses the builder pattern to specify properties for a Context.

Inheritance
object
ContextBuilder
Inherited Members
Namespace: LaunchDarkly.Sdk
Assembly: LaunchDarkly.CommonSdk.dll
Syntax
public sealed class ContextBuilder
Remarks

Use this type if you need to construct a Context that has only a single kind. To define a multi-kind Context, use NewMulti(params Context[]) or MultiBuilder().

Obtain an instance of ContextBuilder by calling Builder(string). Then, call setter methods such as Kind(string), Name(string), or Set(string, string) to specify any additional attributes. Then, call Build() to create the Context. ContextBuilder setters return a reference to the same builder, so calls can be chained: 

var context = Context.Builder("user-key").
    Name("my-name").
    Set("country", "us").
    Build();

A ContextBuilder should not be accessed by multiple threads at once. Once you have called Build(), the resulting Context is immutable and is safe to use from multiple threads. Instances created with Build() are not affected by subsequent actions taken on the builder.

Methods

Anonymous(bool)

Sets whether the Context is only intended for flag evaluations and should not be indexed by LaunchDarkly.

Declaration
public ContextBuilder Anonymous(bool anonymous)
Parameters
Type Name Description
bool anonymous

true if the Context should be excluded from the LaunchDarkly database
Returns
Type Description
ContextBuilder

the builder
Remarks

The default value is false. False means that this Context represents an entity such as a user that you want to be able to see on the LaunchDarkly dashboard.

Setting Anonymous to true excludes this Context from the database that is used by the dashboard. It does not exclude it from analytics event data, so it is not the same as making attributes private; all non-private attributes will still be included in events and data export. There is no limitation on what other attributes may be included (so, for instance, Anonymous does not mean there is no Name(string)), and the Context will still have whatever Key(string) you have given it.

This value is also addressable in evaluations as the attribute name "anonymous". It is always treated as a boolean true or false in evaluations.

See Also

Build()

Creates a Context from the current Builder properties.

Declaration
public Context Build()
Returns
Type Description
Context

a new Context
Remarks

The Context is immutable and will not be affected by any subsequent actions on the ContextBuilder.

It is possible to specify invalid attributes for a ContextBuilder, such as an empty key. Instead of throwing an exception, the ContextBuilder always returns a Context and you can check Error to see if it has an error. See Error for more information about invalid Context conditions. If you pass an invalid Context to an SDK method, the SDK will detect this and will generally log a description of the error.

Key(string)

Sets the Context's key attribute.

Declaration
public ContextBuilder Key(string key)
Parameters
Type Name Description
string key

the context key
Returns
Type Description
ContextBuilder

the builder
Remarks

Every Context has a key, which is always a string. It cannot be an empty string, but there are no other restrictions on its value.

The key attribute can be referenced by flag rules, flag target lists, and segments.

Kind(ContextKind)

Sets the Context's kind attribute.

Declaration
public ContextBuilder Kind(ContextKind kind)
Parameters
Type Name Description
ContextKind kind

the context kind
Returns
Type Description
ContextBuilder

the builder
Remarks

Every Context has a kind. Setting it to an empty string or null is equivalent to Default ("user"). This value is case-sensitive. For validation rules, see ContextKind.

If the value is invalid at the time Build() is called, you will receive an invalid Context whose Error will describe the problem.

See Also

Kind(string)

Sets the Context's kind attribute. This is a shortcut for calling Kind(ContextKind.Of(kindString)), since the method name already prevents ambiguity about the intended type.

Declaration
public ContextBuilder Kind(string kindString)
Parameters
Type Name Description
string kindString

the context kind
Returns
Type Description
ContextBuilder

the builder
See Also

Name(string)

Sets the Context's name attribute.

Declaration
public ContextBuilder Name(string name)
Parameters
Type Name Description
string name

the name attribute (null to unset the attribute)
Returns
Type Description
ContextBuilder

the builder
Remarks

This attribute is optional. It has the following special rules:

  • Unlike most other attributes, it is always a string if it is specified.
  • The LaunchDarkly dashboard treats this attribute as the preferred display name for contexts.
See Also

Private(params AttributeRef[])

Equivalent to Private(params string[]), but uses the AttributeRef type.

Declaration
public ContextBuilder Private(params AttributeRef[] attributeRefs)
Parameters
Type Name Description
AttributeRef[] attributeRefs

attribute references to mark as private
Returns
Type Description
ContextBuilder

the builder
Remarks

Application code is unlikely to need to use the AttributeRef type directly; however, in cases where you are constructing Contexts constructed repeatedly with the same set of private attributes, if you are also using complex private attribute path references such as "/address/street", converting this to an AttributeRef once and reusing it in many Private calls is slightly more efficient than passing a string (since it does not need to parse the path repeatedly).

See Also

Private(params string[])

Designates any number of Context attributes, or properties within them, as private: that is, their values will not be sent to LaunchDarkly.

Declaration
public ContextBuilder Private(params string[] attributeRefs)
Parameters
Type Name Description
string[] attributeRefs

attribute references to mark as private
Returns
Type Description
ContextBuilder

the builder
Remarks

TKTK: conceptual information about private attributes might be in online docs

See Also

Remove(string)

Unsets a previously set attribute value. Has no effect if no such value was set.

Declaration
public ContextBuilder Remove(string attributeName)
Parameters
Type Name Description
string attributeName

the attribute name to unset
Returns
Type Description
ContextBuilder

the builder
See Also

Set(string, LdValue)

Sets the value of any attribute for the Context.

Declaration
public ContextBuilder Set(string attributeName, LdValue value)
Parameters
Type Name Description
string attributeName

the attribute name to set
LdValue value

the value to set
Returns
Type Description
ContextBuilder

the builder
Remarks

This includes only attributes that are addressable in evaluations-- not metadata such as Private(params string[]). If attributeName is "private", you will be setting an attribute with that name which you can use in evaluations or to record data for your own purposes, but it will be unrelated to Private(params string[]).

This method uses the LdValue type to represent a value of any JSON type: null, boolean, number, string, array, or object. For all attribute names that do not have special meaning to LaunchDarkly, you may use any of those types. Values of different JSON types are always treated as different values: for instance, null, false, and the empty string "" are not the the same, and the number 1 is not the same as the string "1".

The following attribute names have special restrictions on their value types, and any value of an unsupported type will be ignored (leaving the attribute unchanged):

The attribute name "_meta" is not allowed, because it has special meaning in the JSON schema for contexts; any attempt to set an attribute with this name has no effect. Also, any attempt to set an attribute with an empty or null name has no effect.

Values that are JSON arrays or objects have special behavior when referenced in flag/segment rules.

A value of Null is equivalent to removing any current non-default value of the attribute. Null is not a valid attribute value in the LaunchDarkly model; any expressions in feature flags that reference an attribute with a null value will behave as if the attribute did not exist.

See Also

Set(string, bool)

Same as Set(string, LdValue) for a boolean value.

Declaration
public ContextBuilder Set(string attributeName, bool value)
Parameters
Type Name Description
string attributeName

the attribute name to set
bool value

the value to set
Returns
Type Description
ContextBuilder

the builder
See Also

Set(string, double)

Same as Set(string, LdValue) for a double-precision numeric value.

Declaration
public ContextBuilder Set(string attributeName, double value)
Parameters
Type Name Description
string attributeName

the attribute name to set
double value

the value to set
Returns
Type Description
ContextBuilder

the builder
Remarks

Numeric values in custom attributes have some precision limitations, the same as for numeric values in flag variations. For more details, see our documentation on flag value types.

See Also

Set(string, int)

Same as Set(string, LdValue) for an integer numeric value.

Declaration
public ContextBuilder Set(string attributeName, int value)
Parameters
Type Name Description
string attributeName

the attribute name to set
int value

the value to set
Returns
Type Description
ContextBuilder

the builder
See Also

Set(string, long)

Same as Set(string, LdValue) for a long integer numeric value.

Declaration
public ContextBuilder Set(string attributeName, long value)
Parameters
Type Name Description
string attributeName

the attribute name to set
long value

the value to set
Returns
Type Description
ContextBuilder

the builder
Remarks

Numeric values in custom attributes have some precision limitations, the same as for numeric values in flag variations. For more details, see our documentation on flag value types.

See Also

Set(string, string)

Same as Set(string, LdValue) for a string value.

Declaration
public ContextBuilder Set(string attributeName, string value)
Parameters
Type Name Description
string attributeName

the attribute name to set
string value

the value to set
Returns
Type Description
ContextBuilder

the builder
See Also

TrySet(string, LdValue)

Same as Set(string, LdValue), but returns a boolean indicating whether the attribute was successfully set.

Declaration
public bool TrySet(string attributeName, LdValue value)
Parameters
Type Name Description
string attributeName

the attribute name to set
LdValue value

the value to set
Returns
Type Description
bool

true if successful; false if the name was invalid or the value was not an allowed type for that attribute
See Also