Show / Hide Table of Contents

Class Context

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

Inheritance
System.Object
Context
Implements
System.IEquatable<Context>
IJsonSerializable
Namespace: LaunchDarkly.Sdk
Assembly: LaunchDarkly.CommonSdk.dll
Syntax
public sealed class Context : ValueType, 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(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
System.Boolean
Remarks

For a single-kind context, this value is set by Anonymous(Boolean). 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(Boolean)

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
System.Boolean
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
System.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
System.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
System.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
System.Collections.Immutable.ImmutableList<Context>
Remarks

If this is a multi-kind Context, then it returns the individual contexts that were passed to NewMulti(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
System.Boolean
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
System.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
System.Collections.Generic.IEnumerable<System.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
System.Collections.Immutable.ImmutableList<AttributeRef>
Remarks

This includes all attribute names/paths that were specified with Private(String[]) or Private(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
System.Boolean
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

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

Equals(Object)

Declaration
public override bool Equals(object other)
Parameters
Type Name Description
System.Object other
Returns
Type Description
System.Boolean

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

GetValue(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
System.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, Boolean). 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(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(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

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

a string representation

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

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

System.IEquatable<>
IJsonSerializable
In This Article
Back to top Generated by DocFX