Show / Hide Table of Contents

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)
In This Article
Back to top Generated by DocFX