How to serialize and deserialize JSON using C # - .NET

01/19/2021 16 minutes to read In this article

This article shows how to use the System.Text.Json namespace to serialize to and deserialize from JavaScript Object Notation (JSON). If you're porting existing code from Newtonsoft.Json, see How to migrate to System.Text.Json.

Code samples

The code samples in this article:

Use the library directly, not through a framework such as ASP.NET Core.

Use the JsonSerializer class with custom types to serialize from and deserialize into.

For information about how to read and write JSON data without using JsonSerializer, see How to use the JSON DOM, Utf8JsonReader, and Utf8JsonWriter.

Use the WriteIndented option to format the JSON for human readability when that is helpful.

For production use, you would typically accept the default value of false for this setting, since adding unnecessary whitespace may incur a negative impact on performance and bandwidth usage.

Refer to the following class and variants of it:

public class WeatherForecast

public DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set;

Public Class WeatherForecastPublic Property [Date] As DateTimeOffsetPublic Property TemperatureCelsius As IntegerPublic Property Summary As String

End Class

Visual Basic support

Parts of System.Text.Json use ref structs, which are not supported by Visual Basic. If you try to use System.Text.Json ref struct APIs with Visual Basic you get BC40000 compiler errors. The error message indicates that the problem is an obsolete API, but the actual issue is lack of ref struct support in the compiler. The following parts of System.Text.Json aren't usable from Visual Basic:

The Utf8JsonReader class. Since the JsonConverter .Read method takes a Utf8JsonReader parameter, this limitation means you can't use Visual Basic to write custom converters. A workaround for this is to implement custom converters in a C # library assembly, and reference that assembly from your VB project. This assumes that all you do in Visual Basic is register the converters into the serializer. You can't call the Read methods of the converters from Visual Basic code. Overloads of other APIs that include a ReadOnlySpan type. Most methods include overloads that use String instead of ReadOnlySpan.

These restrictions are in place because ref structs cannot be used safely without language support, even when just “passing data through.” Subverting this error will result in Visual Basic code that can corrupt memory and should not be done.

Namespaces

The System.Text.Json namespace contains all the entry points and the main types. The System.Text.Json.Serialization namespace contains attributes and APIs for advanced scenarios and customization specific to serialization and deserialization. The code examples shown in this article require using directives for one or both of these namespaces:

using System.Text.Json;

using System.Text.Json.Serialization;

Imports System.Text.Json

Imports System.Text.Json.Serialization

How to write .NET objects as JSON (serialize)

To write JSON to a string or to a file, call the JsonSerializer.Serialize method.

The following example creates JSON as a string:

using System;

using System.Text.Json; namespace SerializeBasic

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public class Programpublic static void Main () var weatherForecast = new WeatherForecastDate = DateTime.Parse (“2019-08-01”), TemperatureCelsius = 25, Summary = “Hot”; string jsonString = JsonSerializer.Serialize (weatherForecast); Console.WriteLine (jsonString);// output:

// “Date”: “2019-08-01T00: 00: 00-07: 00”, “TemperatureCelsius”: 25, “Summary”: “Hot”

Dim jsonString As String

The JSON output is minified (whitespace, indentation, and new-line characters are removed) by default.

The following example uses synchronous code to create a JSON file:

using System;

using System.IO;

using System.Text.Json; namespace SerializeToFile

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public class Programpublic static void Main () var weatherForecast = new WeatherForecastDate = DateTime.Parse (“2019-08-01”), TemperatureCelsius = 25, Summary = “Hot”; string fileName = “WeatherForecast.json”; string jsonString = JsonSerializer .Serialize (weatherForecast); File.WriteAllText (fileName, jsonString); Console.WriteLine (File.ReadAllText (fileName));// output:

// “Date”: “2019-08-01T00: 00: 00-07: 00”, “TemperatureCelsius”: 25, “Summary”: “Hot”

jsonString = JsonSerializer.Serialize (weatherForecast1)

File.WriteAllText (fileName, jsonString)

The following example uses asynchronous code to create a JSON file:

using System;

using System.IO;

using System.Text.Json;

using System.Threading.Tasks; namespace SerializeToFileAsync

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public class Programpublic static async Task Main () var weatherForecast = new WeatherForecastDate = DateTime.Parse (“2019-08-01”), TemperatureCelsius = 25, Summary = “Hot”; string fileName = “WeatherForecast.json”; using FileStream createStream = File.Create (fileName); await JsonSerializer.SerializeAsync (createStream, weatherForecast); await createStream.DisposeAsync (); Console.WriteLine (File.ReadAllText (fileName));// output:

// “Date”: “2019-08-01T00: 00: 00-07: 00”, “TemperatureCelsius”: 25, “Summary”: “Hot”

Dim createStream As FileStream = File.Create (fileName)

Await JsonSerializer.SerializeAsync (createStream, weatherForecast1)

The preceding examples use type inference for the type being serialized. An overload of Serialize () takes a generic type parameter:

using System;

using System.Text.Json; namespace SerializeWithGenericParameter

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public class Programpublic static void Main () var weatherForecast = new WeatherForecastDate = DateTime.Parse (“2019-08-01”), TemperatureCelsius = 25, Summary = “Hot”; string jsonString = JsonSerializer.Serialize (weatherForecast); Console.WriteLine (jsonString);// output:

// “Date”: “2019-08-01T00: 00: 00-07: 00”, “TemperatureCelsius”: 25, “Summary”: “Hot”

jsonString = JsonSerializer.Serialize (Of WeatherForecastWithPOCOs) (weatherForecast)

Serialization example

Here's an example showing how a class that contains collection properties and a user-defined type is serialized:

using System;

using System.Collections.Generic;

using System.Text.Json; namespace SerializeExtra

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public string SummaryField; public IList DatesAvailable get; set; public Dictionary TemperatureRanges get; set; public string [] SummaryWords get; set; public class HighLowTempspublic int High get; set; public int Low get; set; public class Programpublic static void Main () var weatherForecast = new WeatherForecastDate = DateTime.Parse (“2019-08-01”), TemperatureCelsius = 25, Summary = “Hot”, SummaryField = “Hot”, DatesAvailable = new List () DateTime.Parse (“2019-08-01”), DateTime.Parse (“2019-08-02”), TemperatureRanges = new Dictionary [“Cold”] = new HighLowTemps High = 20, Low = -10, [“Hot”] = new HighLowTemps High = 60, Low = 20, SummaryWords = new [] “Cool”, “Windy”, “Humid”; var options = new JsonSerializerOptions WriteIndented = true; string jsonString = JsonSerializer .Serialize (weatherForecast, options); Console.WriteLine (jsonString);// output:

// “Date”: “2019-08-01T00: 00: 00-07: 00”,

// “TemperatureCelsius”: 25,

// “Summary”: “Hot”,

// “DatesAvailable”: [

// “2019-08-01T00: 00: 00-07: 00”,

// “2019-08-02T00: 00: 00-07: 00”

//],

// “TemperatureRanges”:// “Cold”:// “High”: 20,

// “Low”: -10

//,

// “Hot”:// “High”: 60,

// “Low”: 20

//,

// “SummaryWords”: [

// “Cool”,

// “Windy”,

// “Humid”

//]

Public Class WeatherForecastWithPOCOsPublic Property [Date] As DateTimeOffsetPublic Property TemperatureCelsius As IntegerPublic Property Summary As StringPublic SummaryField As StringPublic Property DatesAvailable As IList (Of DateTimeOffset) Public Property TemperatureRanges As Dictionary (Of String, HighLowTemps As) Public Property String (Summary)

End ClassPublic Class HighLowTempsPublic Property High As IntegerPublic Property Low As Integer

End Class' serialization output formatted (pretty-printed with whitespace and indentation):

''”Date”: “2019-08-01T00: 00: 00-07: 00”,

'”TemperatureCelsius”: 25,

'”Summary”: “Hot”,

'”DatesAvailable”: [

'”2019-08-01T00: 00: 00-07: 00″,

'”2019-08-02T00: 00: 00-07: 00″

'],

'”TemperatureRanges”:'”Cold”:'”High”: 20,

'”Low”: -10

'”Hot”:'”High”: 60,

'”Low”: 20

'”SummaryWords”: [

'”Cool”,

'”Windy”,

'”Humid”

'Serialize to UTF-8

Serializing to a UTF-8 byte array is about 5-10% faster than using the string-based methods. The difference is because the bytes (as UTF-8) don't need to be converted to strings (UTF-16).

To serialize to a UTF-8 byte array, call the JsonSerializer.SerializeToUtf8Bytes method:

byte [] jsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes (weatherForecast);

Dim jsonUtf8Bytes As Byte ()

Dim options As JsonSerializerOptions = New JsonSerializerOptions With .WriteIndented = TruejsonUtf8Bytes = JsonSerializer.SerializeToUtf8Bytes (weatherForecast1, options)

A Serialize overload that takes a Utf8JsonWriter is also available.

Serialization behavior

Supported types include:

For more information, see Supported collection types in System.Text.Json.

You can implement custom converters to handle additional types or to provide functionality that isn't supported by the built-in converters.

How to read JSON as .NET objects (deserialize)

To deserialize from a string or a file, call the JsonSerializer.Deserialize method.

The following example shows how to deserialize a JSON string:

using System;

using System.Collections.Generic;

using System.Text.Json; namespace DeserializeExtra

@ “” “Date” “:” “2019-08-01T00: 00: 00-07: 00” “,” “TemperatureCelsius” “: 25,” “Summary” “:” “Hot” “,” “DatesAvailable” “: [” “2019-08-01T00: 00: 00-07: 00” “,” “2019-08-02T00: 00: 00-07: 00” “],” “TemperatureRanges” “:” “Cold” “:” “High” “: 20,” “Low” “: -10,” “Hot” “:” “High” “: 60,” “Low” “: 20,” “SummaryWords” “: [” ” Cool “”, “” Windy “”, “” Humid “”]”; WeatherForecast weatherForecast = JsonSerializer.Deserialize (jsonString); Console.WriteLine ($” Date: weatherForecast.Date “); Console.WriteLine ($” TemperatureCelsius: weatherForecast.TemperatureCelsius “); Console.WriteLine ($” Summary : weatherForecast.Summary “);// output:

// Date: 8/1/2019 12:00:00 AM -07: 00

// TemperatureCelsius: 25

// Summary: Hot

weatherForecast = JsonSerializer.Deserialize (Of WeatherForecastWithPOCOs) (jsonString)

To deserialize from a file by using synchronous code, read the file into a string, as shown in the following example:

using System;

using System.IO;

using System.Text.Json; namespace DeserializeFromFile

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public class Programpublic static void Main () string fileName = “WeatherForecast.json”; string jsonString = File.ReadAllText (fileName); WeatherForecast weatherForecast = JsonSerializer.Deserialize (jsonString); Console.WriteLine ($ “Date: weatherForecast. Date “); Console.WriteLine ($” TemperatureCelsius: weatherForecast.TemperatureCelsius “); Console.WriteLine ($” Summary: weatherForecast.Summary “);// output:

// Date: 8/1/2019 12:00:00 AM -07: 00

// TemperatureCelsius: 25

// Summary: Hot

jsonString = File.ReadAllText (fileName)

weatherForecast1 = JsonSerializer.Deserialize (Of WeatherForecast) (jsonString)

To deserialize from a file by using asynchronous code, call the DeserializeAsync method:

using System;

using System.IO;

using System.Text.Json;

using System.Threading.Tasks; namespace DeserializeFromFileAsync

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public class Programpublic static async Task Main () string fileName = “WeatherForecast.json”; using FileStream openStream = File.OpenRead (fileName); WeatherForecast weatherForecast = await JsonSerializer.DeserializeAsync (openStream); Console.WriteLine ($ “DateLine (openStream); Console.WriteLine ($” DateLine) : weatherForecast.Date “); Console.WriteLine ($” TemperatureCelsius: weatherForecast.TemperatureCelsius “); Console.WriteLine ($” Summary: weatherForecast.Summary “);// output:

// Date: 8/1/2019 12:00:00 AM -07: 00

// TemperatureCelsius: 25

// Summary: Hot

Dim openStream As FileStream = File.OpenRead (fileName)

weatherForecast1 = Await JsonSerializer.DeserializeAsync (Of WeatherForecast) (openStream)

Tip

If you have JSON that you want to deserialize, and you don't have the class to deserialize it into, you have options other than manually creating the class that you need:

Use JsonDocument and Utf8JsonReader directly. Use Visual Studio 2019 to automatically generate the class you need: Copy the JSON that you need to deserialize. Create a class file and delete the template code. Choose Edit> Paste Special> Paste JSON as Classes. The result is a class that you can use for your deserialization target. Deserialize from UTF-8

To deserialize from UTF-8, call a JsonSerializer. The examples assume the JSON is in a byte array named jsonUtf8Bytes.

var readOnlySpan = new ReadOnlySpan (jsonUtf8Bytes);

WeatherForecast deserializedWeatherForecast = JsonSerializer.Deserialize (readOnlySpan);

Dim jsonString = Encoding.UTF8.GetString (jsonUtf8Bytes)

weatherForecast1 = JsonSerializer.Deserialize (Of WeatherForecast) (jsonString)

var utf8Reader = new Utf8JsonReader (jsonUtf8Bytes);

WeatherForecast deserializedWeatherForecast = JsonSerializer.Deserialize (ref utf8Reader);

'This code example doesn't apply to Visual Basic. For more information, go to the following URL:

'https://docs.microsoft.com/dotnet/standard/serialization/system-text-json-how-to#visual-basic-support

Deserialization behavior

The following behaviors apply when deserializing JSON:

By default, property name matching is case-sensitive. You can specify case-insensitivity. ASP.NET Core apps specify case-insensitivity by default. If the JSON contains a value for a read-only property, the value is ignored and no exception is thrown. A parameterless constructor, which can be public, internal, or private, is used for deserialization. Deserialization to immutable objects or properties that don't have public set accessors isn't supported. By default, enums are supported as numbers. You can serialize enum names as strings. Fields aren't supported. By default, comments or trailing commas in the JSON throw exceptions. You can allow comments and trailing commas. The default maximum depth is 64.

When you use System.Text.Json indirectly in an ASP.NET Core app, some default behaviors are different. For more information, see Web defaults for JsonSerializerOptions.

You can implement custom converters to provide functionality that isn't supported by the built-in converters.

Serialize to formatted JSON

To pretty-print the JSON output, set JsonSerializerOptions.WriteIndented to true:

using System;

using System.Text.Json; namespace SerializeWriteIndented

public class WeatherForecastpublic DateTimeOffset Date get; set; public int TemperatureCelsius get; set; public string Summary get; set; public class Programpublic static void Main () var weatherForecast = new WeatherForecastDate = DateTime.Parse (“2019-08-01”), TemperatureCelsius = 25, Summary = “Hot”; var options = new JsonSerializerOptions WriteIndented = true; string jsonString = JsonSerializer .Serialize (weatherForecast, options); Console.WriteLine (jsonString);// output:

// “Date”: “2019-08-01T00: 00: 00-07: 00”,

// “TemperatureCelsius”: 25,

// “Summary”: “Hot”

Dim options As JsonSerializerOptions = New JsonSerializerOptions With .WriteIndented = TruejsonString = JsonSerializer.Serialize (weatherForecast, options)

If you use JsonSerializerOptions repeatedly with the same options, don't create a new JsonSerializerOptions instance each time you use it. Reuse the same instance for every call. For more information, see Reuse JsonSerializerOptions instances.

Include fields

Use the JsonSerializerOptions.IncludeFields global setting or the [JsonInclude] attribute to include fields when serializing or deserializing, as shown in the following example:

using System;

using System.Text.Json;

using System.Text.Json.Serialization; namespace Fields

public class Forecastpublic DateTime Date; public int TemperatureC; public string Summary; public class Forecast2 [JsonInclude] public DateTime Date; [JsonInclude] public int TemperatureC; [JsonInclude] public string Summary; public class Programpublic static void Main () var json = @ “” “Date” “:” “2020-09-06T11: 31: 01.923395” “,” “TemperatureC” “: – 1,” “Summary” “:” “Cold” “”; Console.WriteLine ($ “Input JSON: json “); var options = new JsonSerializerOptionsIncludeFields = true,; var forecast = JsonSerializer.Deserialize (json, options); Console.WriteLine ($” forecast.Date: forecast.Date “); Console.WriteLine ( $ “forecast.TemperatureC: forecast.TemperatureC”); Console.WriteLine ($ “forecast.Summary: forecast.Summary”); var roundTrippedJson = JsonSerializer.Serialize (forecast, options); Console.WriteLine ($ “Output JSON: roundTrippedJson “); var forecast2 = JsonSerializer.Deserialize (json); Console.WriteLine ($” forecast2.Date: forecast2.Date “); Console.WriteLine ($” forecast2.TemperatureC: forecast2.Tempera tureC “); Console.WriteLine ($” forecast2.Summary: forecast2.Summary “); roundTrippedJson = JsonSerializer.Serialize (forecast2); Console.WriteLine ($” Output JSON: roundTrippedJson “);

// Produces output like the following example:

// Input JSON: “Date”: “2020-09-06T11: 31: 01.923395”, “TemperatureC”: – 1, “Summary”: “Cold”

//forecast.Date: 9/6/2020 11:31:01 AM

//forecast.TemperatureC: -1

//forecast.Summary: Cold

// Output JSON: “Date”: “2020-09-06T11: 31: 01.923395”, “TemperatureC”: – 1, “Summary”: “Cold”

//forecast2.Date: 9/6/2020 11:31:01 AM

//forecast2.TemperatureC: -1

//forecast2.Summary: Cold

// Output JSON: “Date”: “2020-09-06T11: 31: 01.923395”, “TemperatureC”: – 1, “Summary”: “Cold”

Imports System.Text.Json

Imports System.Text.Json.SerializationNamespace FieldsPublic Class ForecastPublic [Date] As DatePublic TemperatureC As IntegerPublic Summary As StringEnd ClassPublic Class Forecast2 Public [Date] As Date Public TemperatureC As Integer Public Summary As StringEnd ClassPubitable> Public Summary As StringEnd ClassPublic Class ProgramPublic Shared Sub Main () Dim json As String = “” “Date” “:” “2020-09-06T11: 31: 01.923395” “,” “TemperatureC” “: – 1,” “Summary” “:” ” Cold “” “Console.WriteLine ($” Input JSON: json “) Dim options As New JsonSerializerOptions With .IncludeFields = TrueDim forecast1 As Forecast = JsonSerializer.Deserialize (Of Forecast) (json, options) Console.WriteLine ($” forecast. Date: forecast1. [Date] “) Console.WriteLine ($” forecast.TemperatureC: forecast1.TemperatureC “) Console.WriteLine ($” forecast.Summary: forecast1.Summary “) Dim roundTrippedJson As String = JsonSerializer.Serialize (forecast1, options) Console.WriteLine ($ “Output JSON: roundTrippedJson”) Dim forecast21 As Forecast2 = JsonSerializ er.Deserialize (Of Forecast2) (json) Console.WriteLine ($ “forecast2.Date: forecast21. [Date]”) Console.WriteLine ($ “forecast2.TemperatureC: forecast21.TemperatureC”) Console.WriteLine ($ “forecast2. Summary: forecast21.Summary “) roundTrippedJson = JsonSerializer.Serialize (forecast21) Console.WriteLine ($” Output JSON: roundTrippedJson “) End SubEnd ClassEnd Namespace 'Produces output like the following example:

'Input JSON: “Date”: “2020-09-06T11: 31: 01.923395”, “TemperatureC”: – 1, “Summary”: “Cold”

'forecast.Date: 9/6/2020 11:31:01 AM

'forecast.TemperatureC: -1

'forecast.Summary: Cold

'Output JSON: “Date”: “2020-09-06T11: 31: 01.923395”, “TemperatureC”: – 1, “Summary”: “Cold”

'forecast2.Date: 9/6/2020 11:31:01 AM

'forecast2.TemperatureC: -1

'forecast2.Summary: Cold

'Output JSON: “Date”: “2020-09-06T11: 31: 01.923395”, “TemperatureC”: – 1, “Summary”: “Cold”

To ignore read-only fields, use the JsonSerializerOptions.IgnoreReadOnlyFields global setting.

Fields are not supported in System.Text.Json in .NET Core 3.1. Custom converters can provide this functionality.

HttpClient and HttpContent extension methods

Serializing and deserializing JSON payloads from the network are common operations. Extension methods on HttpClient and HttpContent let you do these operations in a single line of code. These extension methods use web defaults for JsonSerializerOptions.

The following example illustrates use of HttpClientJsonExtensions.GetFromJsonAsync and HttpClientJsonExtensions.PostAsJsonAsync:

using System;

using System.Net.Http;

using System.Net.Http.Json;

using System.Threading.Tasks; namespace HttpClientExtensionMethods

public class Userpublic int Id get; set; public string Name get; set; public string Username get; set; public string Email get; set; public class Programpublic static async Task Main () using HttpClient client = new () BaseAddress = new Uri (“https://jsonplaceholder.typicode.com”); // Get the user information.User user = await client.GetFromJsonAsync (“users / 1”); Console.WriteLine ($ “Id: user.Id”); Console.WriteLine ($ “Name: user.Name”); Console.WriteLine ($ “Username: user.Username”) ; Console.WriteLine ($ “Email: user.Email”); // Post a new user.HttpResponseMessage response = await client.PostAsJsonAsync (“users”, user); Console.WriteLine ($ “(response.IsSuccessStatusCode?” Success “:” Error “) – response.StatusCode”);

// Produces output like the following example but with different names:

// Id: 1

// Name: Tyler King

// Username: Tyler

// Email: Tyler @ contoso.com

// Success – Created

Imports System.Net.Http

Imports System.Net.Http.JsonNamespace HttpClientExtensionMethodsPublic Class UserPublic Property Id As IntegerPublic Property Name As StringPublic Property Username As StringPublic Property Email As StringEnd ClassPublic Class ProgramPublic Shared Async Function Main () As TaskUsing client As New BttpClient = “New TaskUsing client As New BttpClient =”. https://jsonplaceholder.typicode.com “) 'Get the user information.Dim user1 As User = Await client.GetFromJsonAsync (Of User) (” users / 1 “) Console.WriteLine ($” Id: user1.Id “) Console.WriteLine ($ “Name: user1.Name”) Console.WriteLine ($ “Username: user1.Username”) Console.WriteLine ($ “Email: user1.Email”) 'Post a new user.Dim response As HttpResponseMessage = Await client.PostAsJsonAsync (“users”, user1) Console.WriteLine ($ “(If (response.IsSuccessStatusCode,” Success “,” Error “)) – response.StatusCode”) End UsingEnd FunctionEnd ClassEnd Namespace 'Produces output like the following example but with different names:

'Id: 1

Name: Tyler King

Username: Tyler

'Email: Tyler @ contoso.com

'Success – Created

There are also extension methods for System.Text.Json on HttpContent.

Extension methods on HttpClient and HttpContent are not available in System.Text.Json in .NET Core 3.1.

See also System.Text.Json overview Instantiate JsonSerializerOptions instances Enable case-insensitive matching Customize property names and values Ignore properties Allow invalid JSON Handle overflow JSON or use JsonElement or JsonNode Preserve references and handle circular references Deserialize to immutable types and non-public accessors Polymorphic serialization Migrate from Newtonsoft.Json to System.Text.Json Customize character encoding Use DOM, Utf8JsonReader, and Utf8JsonWriter Write custom converters for JSON serialization DateTime and DateTimeOffset support Supported collection types in System.Text.Json System.Text.Json API reference System.Text.Json.Serialization API reference