Developer Documentation

This documentation outlines what each method does, what it returns or the exceptions it throws, and changes that have been made across versions.

Read JSON from a file

System.Text.Json.Nodes.JsonObject viral32111.JsonExtensions.JsonExtensions.ReadFromFile( string filePath )

Description

Parses the contents of the file at the given path (filePath) as a JSON object.

Returns

A JsonObject representing the parsed JSON from the file.

Exceptions

• viral32111.JsonExtensions.JsonParseException if the JSON within the file is malformed or otherwise invalid.
• System.IO.FileNotFoundException if the file at the specified path cannot be found.
  • In this case, a new JSON file should be created using viral32111.JsonExtensions.JsonExtensions.CreateNewFile().

History

• Introduced in 0.1.0.

Create a new JSON file

System.Text.Json.Nodes.JsonObject viral321111.JsonExtensions.JsonExtensions.CreateNewFile( string filePath, JsonObject? jsonObject = null )

Description

Creates or overwrites the file at the given path (filePath) with the given JSON object (jsonObject), or an empty object if not given.

Returns

A JsonObject representing the JSON that was written to the file.

Exceptions

None.

History

• Fixed the file path not being remembered for use with JsonObject.SaveToFile() in 0.1.1.
• Introduced in 0.1.0.

Save JSON to file

void System.Text.Json.Nodes.JsonObject.SaveToFile( string? filePath = null )

Description

Saves this JSON object to the file at the given path (filePath).

Defaults to the path used when reading or creating the file if no path is given.

Returns

Nothing.

Exceptions

None.

History

• Introduced in 0.1.0.

Set nested JSON property

void System.Text.Json.Nodes.JsonObject.NestedSet( string propertyPath, JsonNode? newValue, char propertyDelimiter = viral32111.JsonExtensions.Defaults.NestedPropertyDelimiter )

Description

Sets the nested property in this JSON object at the given path (propertyPath), separated by the given delimiter (propertyDelimiter), to the given value (newValue).

Returns

Nothing.

Exceptions

• viral32111.JsonExtensions.JsonPropertyNullException if one of the property names expected to be a JsonObject is null.

History

• Added propertyDelimiter parameter in 0.3.0.
• Introduced in 0.1.0.

Get nested JSON property

System.Text.Json.Nodes.JsonNode? System.Text.Json.Nodes.JsonObject.NestedGet( string propertyPath, char propertyDelimiter = viral32111.JsonExtensions.Defaults.NestedPropertyDelimiter )

Description

Gets the nested property in this JSON object at the given path (propertyPath), separated by the given delimiter (propertyDelimiter).

Returns

A JsonNode? representing the value of the property. May be null.

Exceptions

• viral32111.JsonExtensions.JsonPropertyNullException if one of the nested parent JSON object properties is null.
• viral32111.JsonExtensions.JsonPropertyNotFoundException if one of the nested JSON object properties does not exist.

History

• Added propertyDelimiter parameter in 0.3.0.
• Throw viral32111.JsonExtensions.JsonPropertyNotFoundException instead of System.Text.Json.JsonException when a nested property does not exist in 0.1.2.
• Introduced in 0.1.0.

Get nested JSON property as type

System.Type System.Text.Json.Nodes.JsonObject.NestedGet<T>( string propertyPath, char propertyDelimiter = viral32111.JsonExtensions.Defaults.NestedPropertyDelimiter )

Description

Gets the nested property in this JSON object at the given path (propertyPath), separated by the given delimiter (propertyDelimiter), as the given data type (T).

Best sticking to primitive data types, JsonObject and JsonArray.

Returns

The value of the property as the given data type (T).

Exceptions

• viral32111.JsonExtensions.JsonPropertyNullException if the value of the property cannot be casted because it is null.

See viral32111.JsonExtensions.JsonObject.NestedGet() for more exceptions that may be thrown.

History

• Added propertyDelimiter parameter in 0.3.0.
• Introduced in 0.1.0.

Has nested JSON property

bool System.Text.Json.Nodes.JsonObject.NestedHas( string propertyPath, char propertyDelimiter = viral32111.JsonExtensions.Defaults.NestedPropertyDelimiter )

Description

Checks if a nested property exists in this JSON object at the given path (propertyPath), separated by the given delimiter (propertyDelimiter).

A null property value counts as the property existing.

Returns

True or False representing if the property exists.

Exceptions

• viral32111.JsonExtensions.JsonPropertyNullException if one of the property names expected to be a JsonObject is null.

History

• Added propertyDelimiter parameter in 0.3.0.
• Introduced in 0.2.0.

List nested JSON properties

string[] System.Text.Json.Nodes.JsonObject.NestedList( char propertyDelimiter = viral32111.JsonExtensions.Defaults.NestedPropertyDelimiter )

Description

Creates a list of paths to all nested properties in this JSON object, with nested objects separated by the given delimiter (propertyDelimiter).

Null property values are included.

Returns

A list of paths to all nested JSON object properties.

Exceptions

None.

History

• Added propertyDelimiter parameter in 0.3.0.
• Introduced in 0.2.0.

Get as typed array

System.Type[] System.Text.Json.Nodes.JsonNode.AsArray<T>()

Converts this JSON node, which must be a JSON array, to a fixed-length typed array of the given data type (T).

Returns

A typed array of the given data type (T) containing the elements within this JSON array.

Exceptions

• viral32111.JsonExtensions.JsonPropertyNullException if a value in the JSON array is null.

History

• Introduced in 0.1.0.

Clone JSON node

System.Text.Json.Nodes.JsonNode? System.Text.Json.Nodes.JsonNode?.Clone()

Creates a copy of this JSON node.

Returns

A copy of this JSON node, or null if this JSON node is null.

Exceptions

None.

History

• Introduced in 0.2.0.