Struct Optional<T>

Namespace

Auth0.ManagementApi.Core

Assembly

Auth0.ManagementApi.dll

Represents a field that can be "not set" (undefined) vs "explicitly set" (defined). Use this for HTTP PATCH requests where you need to distinguish between:

• Undefined: Don't send this field (leave it unchanged on the server)
• Defined with null: Send null (clear the field on the server)
• Defined with value: Send the value (update the field on the server)

public readonly struct Optional<T> : IOptional, IEquatable<Optional<T>>

Type Parameters

T

The type of the value. Use nullable types (T?) for fields that can be null.

Implements

IOptional

IEquatable<Optional<T>>

Inherited Members

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetType()

Extension Methods

OptionalExtensions.AddTo<T>(Optional<T>, Dictionary<string, object?>, string)

OptionalExtensions.IfDefined<T>(Optional<T>, Action<T>)

OptionalExtensions.Map<T, TResult>(Optional<T>, Func<T, TResult>)

Examples

For nullable string fields, use Optional<string?>:

public class UpdateUserRequest
{
    public Optional<string?> Name { get; set; } = Optional<string?>.Undefined;
}

var request = new UpdateUserRequest
{
    Name = "John"  // Will send: { "name": "John" }
};

var request2 = new UpdateUserRequest
{
    Name = Optional<string?>.Of(null)  // Will send: { "name": null }
};

var request3 = new UpdateUserRequest();  // Will send: {} (name not included)

Properties

IsDefined

Returns true if the field is defined (set), even if the value is null. Use this to determine if the field should be included in the HTTP request.

public bool IsDefined { get; }

Property Value

bool

Examples

if (request.Name.IsDefined)
{
    requestBody["name"] = request.Name.Value;  // Include in request (can be null)
}

IsUndefined

Returns true if the field is undefined (not set). Use this to check if the field should be excluded from the HTTP request.

public bool IsUndefined { get; }

Property Value

bool

Examples

if (request.Email.IsUndefined)
{
    // Don't include email in the request - leave it unchanged
}

Undefined

Creates an undefined value - the field will not be included in the HTTP request. Use this as the default value for optional fields.

public static Optional<T> Undefined { get; }

Property Value

Optional<T>

Examples

public Optional<string?> Email { get; set; } = Optional<string?>.Undefined;

Value

Gets the value. The value may be null if T is a nullable type.

public T Value { get; }

Property Value

T

Examples

if (request.Name.IsDefined)
{
    string? name = request.Name.Value;  // Safe - can be null if Optional<string?>
}

// Or check for null explicitly
if (request.Email.IsDefined && request.Email.Value is null)
{
    // Email is explicitly set to null (clear it)
}

Remarks

Always check IsDefined before accessing Value, or use TryGetValue(out T) instead.

Exceptions

InvalidOperationException

Thrown if the value is undefined.

Methods

Equals(Optional<T>)

Indicates whether the current object is equal to another object of the same type.

public bool Equals(Optional<T> other)

Parameters

other Optional<T>

An object to compare with this object.

Returns

bool

true if the current object is equal to the other parameter; otherwise, false.

Equals(object?)

Indicates whether this instance and a specified object are equal.

public override bool Equals(object? obj)

Parameters

obj object

The object to compare with the current instance.

Returns

bool

true if obj and this instance are the same type and represent the same value; otherwise, false.

GetBoxedValue()

Gets the boxed value. Returns null if undefined or if the value is null.

public object? GetBoxedValue()

Returns

object

GetHashCode()

Returns the hash code for this instance.

public override int GetHashCode()

Returns

int

A 32-bit signed integer that is the hash code for this instance.

GetValueOrDefault(T)

Gets the value if defined, otherwise returns the specified default value. Note: If the value is defined as null, this returns null (not the default).

public T GetValueOrDefault(T defaultValue = default)

Parameters

defaultValue T

The value to return if undefined.

Returns

T

The actual value if defined (can be null), otherwise the default value.

Examples

string name = request.Name.GetValueOrDefault("Anonymous");
// If Name is undefined: returns "Anonymous"
// If Name is Of(null): returns null
// If Name is Of("John"): returns "John"

Of(T)

Creates a defined value - the field will be included in the HTTP request. The value can be null if T is a nullable type.

public static Optional<T> Of(T value)

Parameters

value T

The value to set. Can be null if T is nullable (e.g., string?, int?).

Returns

Optional<T>

Examples

// Set to a value
request.Name = Optional<string?>.Of("John");

// Set to null (clears the field)
request.Email = Optional<string?>.Of(null);

// Or use implicit conversion
request.Name = "John";  // Same as Of("John")
request.Email = null;   // Same as Of(null)

ToString()

Returns a string representation of this Optional value.

public override string ToString()

Returns

string

"Undefined" if not set, or "Defined(value)" if set.

TryGetValue(out T)

Tries to get the value. Returns true if the value is defined (even if null).

public bool TryGetValue(out T value)

Parameters

value T

When this method returns, contains the value if defined, or default(T) if undefined. The value may be null if T is nullable.

Returns

bool

True if the value is defined; otherwise, false.

Examples

if (request.Email.TryGetValue(out var email))
{
    requestBody["email"] = email;  // email can be null
}
else
{
    // Email is undefined - don't include in request
}

Operators

operator ==(Optional<T>, Optional<T>)

Determines whether two Optional values are equal.

public static bool operator ==(Optional<T> left, Optional<T> right)

Parameters

left Optional<T>

The first Optional to compare.

right Optional<T>

The second Optional to compare.

Returns

bool

True if the Optional values are equal; otherwise, false.

implicit operator Optional<T>(T)

Implicitly converts a value to Optional<T>.Of(value). This allows natural assignment: request.Name = "John" instead of request.Name = Optional<string?>.Of("John").

public static implicit operator Optional<T>(T value)

Parameters

value T

The value to convert (can be null if T is nullable).

Returns

Optional<T>

operator !=(Optional<T>, Optional<T>)

Determines whether two Optional values are not equal.

public static bool operator !=(Optional<T> left, Optional<T> right)

Parameters

left Optional<T>

The first Optional to compare.

right Optional<T>

The second Optional to compare.

Returns

bool

True if the Optional values are not equal; otherwise, false.