Class ContextBuilder

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

Inheritance

System.Object

ContextBuilder

Namespace: LaunchDarkly.Sdk

Assembly: LaunchDarkly.CommonSdk.dll

Syntax

public sealed class ContextBuilder : Object

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

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

Anonymous

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
System.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)

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
System.String	kindString	the context kind

Returns

Type	Description
ContextBuilder	the builder

See Also

Kind(ContextKind)

Name(String)

Sets the Context's name attribute.

Declaration

public ContextBuilder Name(string name)

Parameters

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

Name

Private(AttributeRef[])

Equivalent to Private(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(String[])

PrivateAttributes

Private(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
System.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

Private(AttributeRef[])

PrivateAttributes

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
System.String	attributeName	the attribute name to unset

Returns

Type	Description
ContextBuilder	the builder

See Also

Set(String, LdValue)

Set(String, LdValue)

Sets the value of any attribute for the Context.

Declaration

public ContextBuilder Set(string attributeName, LdValue value)

Parameters

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

• "kind", "key": Must be a string. See Kind(String) and Key(String).
• "name": Must be a string or null. See Name(String).
• "anonymous": Must be a boolean. See Anonymous(Boolean).

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

TrySet(String, LdValue)

Set(String, Boolean)

Set(String, Int32)

Set(String, Double)

Set(String, Int64)

Set(String, String)

Remove(String)

GetValue(String)

Set(String, Boolean)

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

Declaration

public ContextBuilder Set(string attributeName, bool value)

Parameters

Type	Name	Description
System.String	attributeName	the attribute name to set
System.Boolean	value	the value to set

Returns

Type	Description
ContextBuilder	the builder

See Also

Set(String, LdValue)

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
System.String	attributeName	the attribute name to set
System.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, LdValue)

Set(String, Int32)

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

Declaration

public ContextBuilder Set(string attributeName, int value)

Parameters

Type	Name	Description
System.String	attributeName	the attribute name to set
System.Int32	value	the value to set

Returns

Type	Description
ContextBuilder	the builder

See Also

Set(String, LdValue)

Set(String, Int64)

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

Declaration

public ContextBuilder Set(string attributeName, long value)

Parameters

Type	Name	Description
System.String	attributeName	the attribute name to set
System.Int64	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, LdValue)

Set(String, String)

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

Declaration

public ContextBuilder Set(string attributeName, string value)

Parameters

Type	Name	Description
System.String	attributeName	the attribute name to set
System.String	value	the value to set

Returns

Type	Description
ContextBuilder	the builder

See Also

Set(String, LdValue)

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
System.String	attributeName	the attribute name to set
LdValue	value	the value to set

Returns

Type	Description
System.Boolean	true if successful; false if the name was invalid or the value was not an allowed type for that attribute

See Also

Set(String, LdValue)