JsonExtensions
🟡 Project status: maintenance mode[?]
This library 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 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 JSONNull-safe reading
This library offers many extension methods for JsonElement that allow you to read 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 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 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 helper extension methods on HttpContent and HttpClient:
using JsonExtensions.Http;
var httpClient = new HttpClient();
// Send GET request and retrieve JSON directly
var json = await httpClient.GetJsonAsync("..."); // returns JsonElement
// Read JSON from content
using var request = new HttpRequestMessage(HttpMethod.Post, "...");
using var response = await httpClient.SendAsync(request);
var json = await response.Content.ReadAsJsonAsync(); // returns JsonElementAccessing 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(); // 13Warning: Note this only supports basic paths involving child access operators. It doesn't (yet) have full support for JPath.