Until the release of .Net Core 3, the Asp.Net Core was dependent on Json.NET for its serialization. But with release of .Net Core 3, this dependency is removed and a new API is created. Not only there is no dependency on Json.Net in .Net Core 3 but also this new API is much faster than Json.NET (Newtonsoft). In this post I’m going to go through the what and the why of this API redesign. We are also going to see some examples of this .Net Core 3 new JSON API.
.Net Core 3 New Json API Advantages
.Net Core 3 New Json API Is Faster
The performance of the new JSON API is greatly improved. Partly because it directly encodes and decodes to UTF8 as opposed to transcoding to UTF-16 string instances. It achieve this by leveraging Span<T> that make it possible to represent native memory and arrays in a uniform way.
.Net Core 3 New Json API Has No Dependency On Json.Net
Previously there was a dependency on Json.Net in Asp.Net Core. That meant that the customers didn’t have the option to opt-out of using this framework. This also could cause problems if the user had Json.Net library as part of a different package, but with a different version. Now with release of .Net Core 3, this dependency is removed. The customers can use the built in APIs or switch it with a third party API if they wanted to.
It Support Backward Compatibility Through Packages
This removal of the dependency that we’ve talked about does not mean that there will be any compatibility issues. The use of Json.Net still will be available by Nuget package. The best thing about it is that user now have complete control over what kind of Json serialization API they want to use.
Performance Vs Large Feature Set
The .Net Core new Json API has some benefits in terms of speed and flexibility. But still the Json.Net library is the one with the most features. Not all rich set of features that are available in Json.Net are available on .Net Core new Json API. The user need to choose between the speed of .Net Core 3 native API and the large feature set available in Json.Net when it considers using a Json API.
.Net Core 3 New Json API Speed
I said the new API is much faster than the Json.Net API. But exactly how much more performance can we expect? In the subsequent section we’re going to see how fast these new APIs are according to what Microsoft claims.
System.Text.Json.Utf8JsonReader
Utf8JsonReader is a high-performance, low allocation, forward-only reader for UTF-8 encoded JSON text that reads from a ReadOnlySpan<byte>. It is a foundational low level type and it can be up to 2 times faster than the Json.Net counterpart. It achieves this by not allocating until you need to actualize JSON tokens as (UTF-16) string.
Utf8JsonWriter
Utf8JsonWriter provides a high-performance UTF-8 encoded JSON text from common .NET types. This type is also a foundational low level type that can be used to create custom serializers. According to Microsoft it can be 30-80% faster than using the writer from Newtonsoft.Json.
JsonDocument
JsonDocument provides the ability to parse JSON data and build a read-only Document Object Model (DOM) which we can then randomly access or enumerate. According to Microsoft Parsing a typical JSON payload and accessing all its members using the JsonDocument is 2-3x faster than Newtonsoft.Json with very little allocations for data that is reasonably sized (i.e. < 1 MB).
.Net Core 3 New Json API Usage Examples
I’m going to show you some examples of serialization using the new API based on the object represented below.
If we try to serialize this object using the syntax string json = JsonSerializer.Serialize(weatherForecast);, here ‘s how the JSON will look like.
Serialize to UTF-8
To serialize to UTF-8, call the JsonSerializer.SerializeToUtf8Bytes method.
byte[] utf8Json = JsonSerializer.SerializeToUtf8Bytes<WeatherForecast>(weatherForecast);
This method of serialization is faster because it does not have to be converted into UTF16.
Deserialize from UTF-8
JsonSerializer.Deserialize will deserialize from UTF-8, we can call a overload that takes a Utf8JsonReader or a ReadOnlySpan<byte>.
We can also directly use Utf8JsonReader and Utf8JsonWriter directly. You can take a look at this document for more in depth examples.
Summary
In this post, I introduced the new Json API and its features. We also saw what was the motivation behind its creation. I then discussed how it can help us in performance sensitive situations and saw some examples of its usage.