JsonWebTokenExtensions Class
Provides extension methods for handling JSON data within JWTs.
public static class JsonWebTokenExtensionsInheritance System.Object → JsonWebTokenExtensions
Methods
JsonWebTokenExtensions.GetArrayOfStrings(this JsonObject, string) Method
Retrieves an array of strings from a System.Text.Json.Nodes.JsonObject based on a specified property name. This method supports both single string values and arrays of strings.
public static System.Collections.Generic.IEnumerable<string> GetArrayOfStrings(this System.Text.Json.Nodes.JsonObject json, string name);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject from which to retrieve the array of strings.
name System.String
The property name to retrieve the values from.
Returns
System.Collections.Generic.IEnumerable<System.String>
An enumerable of strings if the property exists; otherwise, an empty enumerable.
Remarks
This method is useful for JWT claims or other JSON structures where a property may contain either a single string value or an array of strings.
JsonWebTokenExtensions.GetArrayOfStringsOrNull(this JsonObject, string) Method
Retrieves an array of strings from a System.Text.Json.Nodes.JsonObject based on a specified property name,
or returns null if the property does not exist.
public static System.Collections.Generic.IEnumerable<string>? GetArrayOfStringsOrNull(this System.Text.Json.Nodes.JsonObject json, string name);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject from which to retrieve the array of strings.
name System.String
The property name to retrieve the values from.
Returns
System.Collections.Generic.IEnumerable<System.String>
An enumerable of strings if the property exists; otherwise, null.
Remarks
This method is useful when distinguishing between a missing property (null) and a property
that is present but empty. It supports both single string values and arrays of strings.
JsonWebTokenExtensions.GetSpaceSeparatedStrings(this JsonObject, string) Method
Retrieves a collection of strings from a space-separated string stored in a specified property of a System.Text.Json.Nodes.JsonObject.
public static System.Collections.Generic.IEnumerable<string> GetSpaceSeparatedStrings(this System.Text.Json.Nodes.JsonObject json, string name);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject from which to retrieve the space-separated strings.
name System.String
The name of the property containing the space-separated string.
Returns
System.Collections.Generic.IEnumerable<System.String>
An enumerable of strings if the property exists and contains values; otherwise, an empty enumerable.
Remarks
This method simplifies extracting multiple values from a single string property, common in JWT and OAuth scenarios.
JsonWebTokenExtensions.GetUnixTimeSeconds(this JsonObject, string) Method
Retrieves a System.DateTimeOffset value from a System.Text.Json.Nodes.JsonObject based on a property stored as Unix time seconds.
public static System.Nullable<System.DateTimeOffset> GetUnixTimeSeconds(this System.Text.Json.Nodes.JsonObject json, string name);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject from which to retrieve the date/time value.
name System.String
The property name containing the Unix time seconds.
Returns
System.Nullable<System.DateTimeOffset>
A nullable System.DateTimeOffset representing the date and time of the specified property,
or null if the property is not present.
Exceptions
System.InvalidOperationException
The value is not a number.
System.Text.Json.JsonException
The value is a JSON kind no number can be read from.
System.ArgumentOutOfRangeException
The number is outside the range a date can hold.
Remarks
Unix time seconds are widely used for representing date and time in JSON objects, especially in JWTs. This method simplifies retrieving such values by converting them directly to System.DateTimeOffset. A value that is present and cannot be read THROWS rather than answering null: a caller judging a token somebody else wrote reads through TryReadTimestamp(string, Nullable<DateTimeOffset>, string) instead, which names the claim in a refusal.
JsonWebTokenExtensions.SetArrayOrNull(this JsonObject, string, IEnumerable<string>) Method
Assigns a collection of strings to a property as a JSON array whatever its length, or removes the
property when the collection is null or empty.
public static void SetArrayOrNull(this System.Text.Json.Nodes.JsonObject json, string name, System.Collections.Generic.IEnumerable<string>? values);Parameters
json System.Text.Json.Nodes.JsonObject
The object to write to.
name System.String
The name of the property.
values System.Collections.Generic.IEnumerable<System.String>
The values to assign, or null to remove the property.
Remarks
The single-element case is the whole difference from SetArrayOrStringOrNull(this JsonObject, string, IEnumerable<string>), and it is why both exist. A JWT claim a specification defines as "a string or an array of strings" - aud, per RFC 7519 Section 4.1.3 - may collapse; a member defined as "an array of strings" may not, and writing a bare string there produces a document that parses and does not conform. Neither reader complains, so the divergence is only ever noticed by the party that rejects the token.
JsonWebTokenExtensions.SetArrayOrString(this JsonObject, string, IEnumerable<string>) Method
Sets a property in a System.Text.Json.Nodes.JsonObject with a value that can be either a single string or an array of strings, depending on the number of items in the provided enumerable.
public static void SetArrayOrString(this System.Text.Json.Nodes.JsonObject json, string name, System.Collections.Generic.IEnumerable<string> values);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject to modify.
name System.String
The name of the property to set.
values System.Collections.Generic.IEnumerable<System.String>
The enumerable of string values to set as the property's value.
Remarks
This method is versatile for JWT or JSON handling where a property may accept both single and multiple values.
JsonWebTokenExtensions.SetArrayOrStringOrNull(this JsonObject, string, IEnumerable<string>) Method
Sets a property on a System.Text.Json.Nodes.JsonObject to either a single string, a JSON array of strings, or null,
depending on the contents of the provided values collection.
public static void SetArrayOrStringOrNull(this System.Text.Json.Nodes.JsonObject json, string name, System.Collections.Generic.IEnumerable<string>? values);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject to update.
name System.String
The name of the property to set.
values System.Collections.Generic.IEnumerable<System.String>
The collection of string values to assign. If null, the property is set to null.
If the collection contains a single value, it is stored as a string; if multiple values, as a JSON array.
Remarks
This method is useful for serializing claims or properties where the value can be a single string, an array of strings, or omitted entirely (null), such as in JWT payloads or OpenID Connect claims.
JsonWebTokenExtensions.SetSpaceSeparatedStrings(this JsonObject, string, IEnumerable<string>) Method
Sets a property in a System.Text.Json.Nodes.JsonObject with a value represented as a space-separated string from an enumerable of strings.
public static void SetSpaceSeparatedStrings(this System.Text.Json.Nodes.JsonObject json, string name, System.Collections.Generic.IEnumerable<string> value);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject to modify.
name System.String
The name of the property to set.
value System.Collections.Generic.IEnumerable<System.String>
The enumerable of string values to join into a space-separated string.
Remarks
This method is useful for setting JWT claims or other JSON properties that accept a list of values as a single space-separated string.
JsonWebTokenExtensions.SetUnixTimeSeconds(this JsonObject, string, Nullable<DateTimeOffset>) Method
Sets a System.DateTimeOffset value in a System.Text.Json.Nodes.JsonObject, stored as Unix time seconds.
public static void SetUnixTimeSeconds(this System.Text.Json.Nodes.JsonObject json, string name, System.Nullable<System.DateTimeOffset> value);Parameters
json System.Text.Json.Nodes.JsonObject
The System.Text.Json.Nodes.JsonObject to modify.
name System.String
The property name under which to store the Unix time seconds.
value System.Nullable<System.DateTimeOffset>
The System.DateTimeOffset value to set. If null,
the property will be removed from the JSON object.
Remarks
Storing dates as Unix time seconds is a common practice in JWTs and other JSON structures. This method facilitates setting such values by converting System.DateTimeOffset to Unix time seconds.
JsonWebTokenExtensions.ToJsonElement(this JsonNode) Method
Converts a JsonNode to a JsonElement.
public static System.Text.Json.JsonElement ToJsonElement(this System.Text.Json.Nodes.JsonNode? jsonNode);Parameters
jsonNode System.Text.Json.Nodes.JsonNode
The JsonNode to convert.
Returns
System.Text.Json.JsonElement
The converted JsonElement.
JsonWebTokenExtensions.ToJsonNode(this JsonElement) Method
Converts a JsonElement to a JsonNode, allowing for more dynamic manipulation of the JSON structure.
public static System.Text.Json.Nodes.JsonNode? ToJsonNode(this System.Text.Json.JsonElement jsonElement);Parameters
jsonElement System.Text.Json.JsonElement
The JsonElement to convert.
Returns
System.Text.Json.Nodes.JsonNode
The converted JsonNode.
Remarks
This method is useful when you need to convert from a structured JsonElement to a more flexible JsonNode.