JsonExtensions

Development of this project is entirely funded by the community. Consider donating to support!

JsonExtensions is a library that provides a set of helpful utilities for types defined in the System.Text.Json namespace.

Terms of use^[?]

By using this project or its source code, for any purpose and in any shape or form, you grant your implicit agreement to all the following statements:

You condemn Russia and its military aggression against Ukraine
You recognize that Russia is an occupant that unlawfully invaded a sovereign state
You support Ukraine's territorial integrity, including its claims over temporarily occupied territories of Crimea and Donbas
You reject false narratives perpetuated by Russian state propaganda

To learn more about the war and how you can help, click here. Glory to Ukraine! 🇺🇦

Install

📦 NuGet: dotnet add package JsonExtensions

Usage

Parsing JsonElement

You can use the static methods on the Json class to parse JSON directly into a stateless JsonElement instance, without having to deal with JsonDocument in the process:

using JsonExtensions;

var jsonRaw = "{ \"foo\": \"bar\" }";

var jsonElement = Json.Parse(jsonRaw); // returns JsonElement
var jsonElement = Json.TryParse(jsonRaw); // returns null in case of invalid JSON

Null-safe reading

This library offers many extension methods for JsonElement that allow you to read its content in a more fault-tolerant way:

using JsonExtensions.Reading;

var jsonElement = ...;

// Gets a property or returns null if:
// - element is not an object
// - property does not exist
// - property value is null
var maybeProperty = jsonElement.GetPropertyOrNull("prop");

// Gets an array child or returns null if:
// - element is not an array
// - index is out of bounds
// - child is null
var maybeChild = jsonElement.GetByIndexOrNull(3);

// Gets the value converted into the specified type or returns null if:
// - element is null
// - element kind does not match the specified type
// - the value cannot be parsed into the specified type
var maybeString = jsonElement.GetStringOrNull();
var maybeInt32 = jsonElement.GetInt32OrNull();
var maybeGuid = jsonElement.GetGuidOrNull();

// Gets the value coerced into the specified type or returns null if:
// - element is null
// - element kind does not match the specified type or a string
// - the value cannot be parsed into the specified type
var maybeInt32Coerced = jsonElement.GetInt32CoercedOrNull();
var maybeDoubleCoerced = jsonElement.GetDoubleCoercedOrNull();

// Enumerates an array or returns null if:
// - element is not an array
var arrayEnumerator = jsonElement.EnumerateArrayOrNull();

// Enumerates an object or returns null if:
// - element is not an object
var objectEnumerator = jsonElement.EnumerateObjectOrNull();

// Enumerates an array or returns an empty enumerator if:
// - element is not an array
foreach (var child in jsonElement.EnumerateArrayOrEmpty())
{
    // ...
}

// Enumerates an object or returns an empty enumerator if:
// - element is not an object
foreach (var (name, child) in jsonElement.EnumerateObjectOrEmpty())
{
    // ...
}

Most of these methods can also be chained together using the null-conditional operator:

// Returns null if:
// - element is not an object
// - property does not exist
// - property value is null
// - property value cannot be converted into the specified type
var maybeInt32 = jsonElement.GetPropertyOrNull("prop")?.GetInt32OrNull();

Null-safe writing

Similarly, there are also extension methods for Utf8JsonWriter that allow writing nullable versions of common value types:

using JsonExtensions.Writing;

var writer = new Utf8JsonWriter(...);

// Writes "prop":true
writer.WriteBoolean("prop", new bool?(true));

// Writes "prop":null
writer.WriteBoolean("prop", new bool?());

Parsing JSON from HTTP

To make it easier to read JSON that comes from HTTP responses, this library also provides a few extension methods for HttpContent and HttpClient:

using JsonExtensions.Http;

var http = new HttpClient();

// Send a GET request and retrieve JSON directly
var json = await http.GetJsonAsync("..."); // returns JsonElement

// Read JSON from content
using var request = new HttpRequestMessage(HttpMethod.Post, "...");
using var response = await http.SendAsync(request);
var json = await response.Content.ReadAsJsonAsync(); // returns JsonElement

Accessing children by path

Using jsonElement.GetPropertyByPathOrNull(...) or jsonElement.GetPropertyByPath(...), you can get an inner child by its path:

var json = Json.Parse("{\"foo\":{\"bar\":{\"baz\":13}}}");

var child = json.GetPropertyByPath("foo.bar.baz");

var value = child.GetInt32(); // 13

Warning: Note this only supports basic paths involving child access operators. It doesn't (yet) have full support for JPath.

WaleedLab/JsonExtensions