Struct Context

A collection of attributes that can be referenced in flag evaluations and analytics events.

Implements

IEquatable<Context>

IJsonSerializable

Inherited Members

object.GetType()

object.Equals(object, object)

object.ReferenceEquals(object, object)

Namespace: LaunchDarkly.Sdk

Assembly: LaunchDarkly.CommonSdk.dll

Syntax

[JsonConverter(typeof(LdJsonConverters.ContextConverter))]
public readonly struct Context : IEquatable<Context>, IJsonSerializable

Remarks

Context is the newer replacement for the previous, less flexible User type. The current SDK still supports User, but Context is now the preferred model and may entirely replace User in the future.

To create a Context of a single kind, such as a user, you may use New(string) or New(ContextKind, string) when only the key matters; or, to specify other attributes, use Builder(string).

To create a Context with multiple kinds, use NewMulti(params Context[]) or MultiBuilder().

An uninitialized Context struct is not valid for use in any SDK operations. Also, a Context can be in an error state if it was built with invalid attributes. See Error.

A Context can be converted to or from JSON using a standard schema; see LdJsonConverters.ContextConverter.

To learn more about contexts, read the documentation.

Properties

Anonymous

True if this Context is only intended for flag evaluations and will not be indexed by LaunchDarkly.

Declaration

public bool Anonymous { get; }

Property Value

Type	Description
bool

Remarks

For a single-kind context, this value is set by Anonymous(bool). It is false if no value was set.

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), and the Context will still have whatever Key you have given it.

For a multi-kind context, there is no single value and Anonymous returns false. Use MultiKindContexts or TryGetContextByKind(ContextKind, out Context) to inspect a Context for a particular kind, then get the Anonymous value from it.

See Also

Anonymous(bool)

Defined

True if this is a Context that was created with a constructor or builder (regardless of whether its properties are valid), or false if it is an empty uninitialized struct.

Declaration

public bool Defined { get; }

Property Value

Type	Description
bool

See Also

Valid

Error

Error

Null for a valid Context, or an error message for an invalid Context.

Declaration

public string Error { get; }

Property Value

Type	Description
string

Remarks

If this is null, then Valid is true. If it is non-null, then Valid is false.

See Also

Valid

Defined

FullyQualifiedKey

A string that describes the entire Context based on Kind and Key values.

Declaration

public string FullyQualifiedKey { get; }

Property Value

Type	Description
string

Remarks

This value is used whenever LaunchDarkly needs a string identifier based on all of the Kind and Key values in the context; the SDK may use this for caching previously seen contexts, for instance.

Key

The Context's key attribute.

Declaration

public string Key { get; }

Property Value

Type	Description
string

Remarks

For a single-kind context, this value is set by a Context factory method (New(string), New(ContextKind, string)), or by Builder(string) or Key(string).

For a multi-kind context, there is no single value and Key return an empty string. Use MultiKindContexts or TryGetContextByKind(ContextKind, out Context) to inspect a Context for a particular kind, then get the Key from it.

This value is never null.

See Also

Key(string)

Kind

The Context's kind attribute.

Declaration

public ContextKind Kind { get; }

Property Value

Type	Description
ContextKind

Remarks

Every valid Context has a non-empty kind. For multi-kind contexts, this value is "multi" and the kinds within the Context can be inspected with MultiKindContexts or TryGetContextByKind(ContextKind, out Context).

MultiKindContexts

Returns all of the individual contexts Contained in a multi-kind Context.

Declaration

public ImmutableList<Context> MultiKindContexts { get; }

Property Value

Type	Description
ImmutableList<Context>

Remarks

If this is a multi-kind Context, then it returns the individual contexts that were passed to NewMulti(params Context[]) or Add(Context). The ordering is not guaranteed to be the same.

If this is a single-kind Context, then it returns an empty list.

See Also

TryGetContextByKind(ContextKind, out Context)

Multiple

True for a multi-kind Context, or false for a single-kind Context.

Declaration

public bool Multiple { get; }

Property Value

Type	Description
bool

Remarks

If this value is true, then Kind is guaranteed to be "multi", and you can inspect the individual Contexts for each kind with MultiKindContexts or TryGetContextByKind(ContextKind, out Context).

If this value is false, then Kind is guaranteed to have a value that is not "multi"/

Name

The Context's optional name attribute.

Declaration

public string Name { get; }

Property Value

Type	Description
string

Remarks

For a single-kind context, this value is set by Name(string). It is null if no value was set.

For a multi-kind context, there is no single value and Name returns null. Use MultiKindContexts or TryGetContextByKind(ContextKind, out Context) to inspect a Context for a particular kind, then get the Name from it.

See Also

Name(string)

OptionalAttributeNames

Enumerates the names of all regular optional attributes defined on this Context.

Declaration

public IEnumerable<string> OptionalAttributeNames { get; }

Property Value

Type	Description
IEnumerable<string>

Remarks

These do not include attributes that always have a value (Kind, Key, Anonymous), or metadata that is not an attribute addressable in targeting rules (PrivateAttributes). They include any attributes with application-defined names that have a value, and also "name" if Name has a value.

PrivateAttributes

The list of all attribute references marked as private for this specific Context.

Declaration

public ImmutableList<AttributeRef> PrivateAttributes { get; }

Property Value

Type	Description
ImmutableList<AttributeRef>

Remarks

This includes all attribute names/paths that were specified with Private(params string[]) or Private(params AttributeRef[]). If there are none, it is an empty list (never null).

Valid

True for a valid Context, false for an invalid Context.

Declaration

public bool Valid { get; }

Property Value

Type	Description
bool

Remarks

A valid Context is one that can be used in SDK operations. An invalid Context is one that is missing necessary attributes or has invalid attributes, indicating an incorrect usage of the SDK API. The only ways for a Context to be invalid are:

• It has a disallowed value for the Kind property. See Kind(string).
• It is a single-kind Context whose Key is empty.
• It is a multi-kind Context that does not have any kinds. See MultiBuilder().
• It is a multi-kind Context where the same kind appears more than once.
• It is a multi-kind Context where at least one of the nested Contexts had an error.
• It was created with FromUser(User) from a null User reference, or from a User that had a null key.
• It is an uninitialized struct (new Context()).

Since in normal usage it is easy for applications to be sure they are using context kinds correctly, and because throwing an exception is undesirable in application code that uses LaunchDarkly, and because some states such as the empty value are impossible to prevent in .NET, the SDK stores the error state in the Context itself and checks for such errors at the time the Context is used, such as in a flag evaluation. At that point, if the Context is invalid, the operation will fail in some well-defined way as described in the documentation for that method, and the SDK will generally log a warning as well. But in any situation where you are not sure if you have a valid Context, you can check the Error property.

See Also

Error

Defined

Methods

Builder(ContextKind, string)

Equivalent to Builder(string), but sets the initial value of Kind(ContextKind) as well as the key.

Declaration

public static ContextBuilder Builder(ContextKind kind, string key)

Parameters

Type	Name	Description
ContextKind	kind	the context kind
string	key	the context key

Returns

Type	Description
ContextBuilder	a builder

See Also

New(ContextKind, string)

Builder(string)

MultiBuilder()

BuilderFromContext(Context)

Builder(string)

Creates a ContextBuilder for building a Context, initializing its Key(string) and setting Kind(string) to Default.

Declaration

public static ContextBuilder Builder(string key)

Parameters

Type	Name	Description
string	key	the context key

Returns

Type	Description
ContextBuilder	a builder

Remarks

You may use ContextBuilder methods to set additional attributes and/or change the Kind(string) before calling Build(). If you do not change any values, the defaults for the Context are that its Kind is Default ("user"), its Key is set to whatever value you passed for key, its Anonymous attribute is false, and it has no values for any other attributes.

This method is for building a Context that has only a single Kind. To define a multi-kind Context, use NewMulti(params Context[]) or MultiBuilder().

If key is an empty string, there is no default. A Context must have a non-empty key, so if you call Build() in this state without using Key(string) to set the key, you will get an invalid Context.

See Also

New(string)

Builder(ContextKind, string)

MultiBuilder()

BuilderFromContext(Context)

BuilderFromContext(Context)

Creates a ContextBuilder whose properties are the same as an existing single-kind Context. You may then change the ContextBuilder's state in any way and call Build() to create a new independent Context.

Declaration

public static ContextBuilder BuilderFromContext(Context context)

Parameters

Type	Name	Description
Context	context	the context to copy from

Returns

Type	Description
ContextBuilder	a builder

See Also

Builder(string)

Equals(Context)

Declaration

public bool Equals(Context other)

Parameters

Type	Name	Description
Context	other

Returns

Type	Description
bool

Equals(object)

Declaration

public override bool Equals(object other)

Parameters

Type	Name	Description
object	other

Returns

Type	Description
bool

Overrides

ValueType.Equals(object)

FromUser(User)

Converts a User to an equivalent Context instance.

Declaration

public static Context FromUser(User user)

Parameters

Type	Name	Description
User	user	a User object

Returns

Type	Description
Context	a Context with the same attributes as the User

Remarks

This method is used by the SDK whenever an application passes a User instance to methods such as Identify. The SDK operates internally on the Context model, which is more flexible than the older User model: a User can always be converted to a Context, but not vice versa. The Kind of the resulting Context is Default ("user").

Because there is some overhead to this conversion, it is more efficient for applications to construct a Context and pass that to the SDK, rather than a User. This is also recommended because the User type may be removed in a future version of the SDK.

If the user parameter is null, or if the user has a null key, the method returns a Context in an invalid state (see Valid).

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
int

Overrides

ValueType.GetHashCode()

GetValue(in AttributeRef)

Looks up the value of any attribute of the Context, or a value contained within an attribute, based on an AttributeRef. This includes only attributes that are addressable in evaluations-- not metadata such as PrivateAttributes.

Declaration

public LdValue GetValue(in AttributeRef attributeRef)

Parameters

Type	Name	Description
AttributeRef	attributeRef	an attribute reference

Returns

Type	Description
LdValue	the value or Null

Remarks

This implements the same behavior that the SDK uses to resolve attribute references during a flag evaluation. In a single-kind context, the AttributeRef can represent a simple attribute name-- either a built-in one like "name" or "key", or a custom attribute that was set by methods like Set(string, string)-- or, it can be a a slash-delimited path using a JSON-Pointer-like syntax. See AttributeRef for more details.

For a multi-kind context, the only supported attribute name is "kind". Use MultiKindContexts or TryGetContextByKind(ContextKind, out Context) to inspect a Context for a particular kind and then get its attributes.

If the value is found, the return value is the attribute value, using the type LdValue to represent a value of any JSON type).

If there is no such attribute, or if the AttributeRef is invalid, the return value is Null. An attribute that actually exists cannot have a null value.

See Also

GetValue(string)

GetValue(string)

Looks up the value of any attribute of the Context by name. This includes only attributes that are addressable in evaluations-- not metadata such as PrivateAttributes.

Declaration

public LdValue GetValue(string attributeName)

Parameters

Type	Name	Description
string	attributeName	the desired attribute name

Returns

Type	Description
LdValue	the value or Null

Remarks

For a single-kind context, the attribute name can be any custom attribute that was set by methods like Set(string, bool). It can also be one of the built-in ones like "kind", "key", or "name"; in such cases, it is equivalent to Kind, Key, or Name, except that the value is returned using the general-purpose LdValue type.

For a multi-kind context, the only supported attribute name is "kind". Use MultiKindContexts or TryGetContextByKind(ContextKind, out Context) to inspect a Context for a particular kind and then get its attributes.

This method does not support complex expressions for getting individual values out of JSON objects or arrays, such as "/address/street". Use GetValue(in AttributeRef) with an AttributeRef for that purpose.

If the value is found, the return value is the attribute value, using the type LdValue to represent a value of any JSON type.

If there is no such attribute, the return value is Null. An attribute that actually exists cannot have a null value.

See Also

GetValue(in AttributeRef)

MultiBuilder()

Creates a ContextMultiBuilder for building a Context.

Declaration

public static ContextMultiBuilder MultiBuilder()

Returns

Type	Description
ContextMultiBuilder	a builder

Remarks

This method is for building a Context athat has multiple Kind values, each with its own nested Context. To define a single-kind context, use Builder(string) instead.

New(ContextKind, string)

Creates a single-kind Context with only the Kind and Key properties specified.

Declaration

public static Context New(ContextKind kind, string key)

Parameters

Type	Name	Description
ContextKind	kind	the context kind
string	key	the context key

Returns

Type	Description
Context	a Context

Remarks

To specify additional properties, use Builder(string). To create a multi-kind Context, use NewMulti(params Context[]) or MultiBuilder().

See Also

New(string)

Builder(string)

New(string)

Creates a single-kind Context with a Kind of Default and the specified key.

Declaration

public static Context New(string key)

Parameters

Type	Name	Description
string	key	the context key

Returns

Type	Description
Context	a Context

Remarks

To specify additional properties, use Builder(string). To create a multi-kind Context, use NewMulti(params Context[]) or MultiBuilder(). To create a single-kind Context of a different kind than "user", use New(ContextKind, string).

See Also

New(ContextKind, string)

Builder(string)

NewMulti(params Context[])

Creates a multi-kind Context out of the specified single-kind Contexts.

Declaration

public static Context NewMulti(params Context[] contexts)

Parameters

Type	Name	Description
Context[]	contexts	a list of contexts

Returns

Type	Description
Context	a multi-kind Context

Remarks

To create a single-kind Context, use New(string), New(ContextKind, string), or Builder(string).

For the returned Context to be valid, the contexts list must not be empty, and all of its elements must be valid Contexts. Otherwise, the returned Context will be invalid as reported by Error.

If only one context parameter is given, NewMulti(params Context[]) returns a single-kind context (that is, just that same context) rather than a multi-kind context.

If a nested context is multi-kind, this is exactly equivalent to adding each of the individual kinds from it separately. For instance, in the following example, "multi1" and "multi2" end up being exactly the same:

var c1 = Context.New(ContextKind.Of("kind1"), "key1");
var c2 = Context.New(ContextKind.Of("kind2"), "key2");
var c3 = Context.New(ContextKind.Of("kind3"), "key3");
var multi1 = Context.NewMulti(c1, c2, c3);
var c1plus2 = Context.NewMulti(c1, c2);
var multi2 = Context.NewMulti(c1plus2, c3);

See Also

MultiBuilder()

ToString()

Returns a string representation of the Context.

Declaration

public override string ToString()

Returns

Type	Description
string	a string representation

Overrides

ValueType.ToString()

Remarks

For a valid Context, this is currently defined as being the same as the JSON representation, since that is the simplest way to represent all of the Context properties. However, application code should not rely on ToString() always being the same as the JSON representation. If you specifically want the latter, use SerializeObject<T>(T). For an invalid Context, ToString() returns a description of why it is invalid.

TryGetContextByKind(ContextKind, out Context)

Gets the single-kind context, if any, whose Kind matches the specified value exactly.

Declaration

public bool TryGetContextByKind(ContextKind kind, out Context context)

Parameters

Type	Name	Description
ContextKind	kind	the desired context kind
Context	context	receives the context that was found, if successful

Returns

Type	Description
bool	true if found, false if not found

Remarks

If the method is called on a single-kind context, then the specified kind must match the Kind of that context. If the method is called on a multi-kind context, then the kind can match any of the individual contexts within.

Implements

IEquatable<T>

IJsonSerializable