How to write custom converters for JSON serialization (marshalling) in .NET
This article shows how to create custom converters for the JSON serialization classes that are provided in the System.Text.Json namespace. For an introduction to System.Text.Json
, see How to serialize and deserialize JSON in .NET.
A converter is a class that converts an object or a value to and from JSON. The System.Text.Json
namespace has built-in converters for most primitive types that map to JavaScript primitives. You can write custom converters to override the default behavior of a built-in converter. For example:
- You might want
DateTime
values to be represented by mm/dd/yyyy format. By default, ISO 8601-1:2019 is supported, including the RFC 3339 profile. For more information, see DateTime and DateTimeOffset support in System.Text.Json. - You might want to serialize a POCO as JSON string, for example, with a
PhoneNumber
type.
You can also write custom converters to customize or extend System.Text.Json
with new functionality. The following scenarios are covered later in this article:
Visual Basic can't be used to write custom converters but can call converters that are implemented in C# libraries. For more information, see Visual Basic support.
Custom converter patterns
There are two patterns for creating a custom converter: the basic pattern and the factory pattern. The factory pattern is for converters that handle type Enum
or open generics. The basic pattern is for non-generic and closed generic types. For example, converters for the following types require the factory pattern:
Some examples of types that can be handled by the basic pattern include:
The basic pattern creates a class that can handle one type. The factory pattern creates a class that determines, at run time, which specific type is required and dynamically creates the appropriate converter.
Sample basic converter
The following sample is a converter that overrides default serialization for an existing data type. The converter uses mm/dd/yyyy format for DateTimeOffset
properties.
using System.Globalization;
using System.Text.Json;
using System.Text.Json.Serialization;
namespace SystemTextJsonSamples
{
public class DateTimeOffsetJsonConverter : JsonConverter<DateTimeOffset>
{
public override DateTimeOffset Read(
ref Utf8JsonReader reader,
Type typeToConvert,
JsonSerializerOptions options) =>
DateTimeOffset.ParseExact(reader.GetString()!,
"MM/dd/yyyy", CultureInfo.InvariantCulture);
public override void Write(
Utf8JsonWriter writer,
DateTimeOffset dateTimeValue,
JsonSerializerOptions options) =>
writer.WriteStringValue(dateTimeValue.ToString(
"MM/dd/yyyy", CultureInfo.InvariantCulture));
}
}
Sample factory pattern converter
The following code shows a custom converter that works with Dictionary<Enum,TValue>
. The code follows the factory pattern because the first generic type parameter is Enum
and the second is open. The CanConvert
method returns true
only for a Dictionary
with two generic parameters, the first of which is an Enum
type. The inner converter gets an existing converter to handle whichever type is provided at run time for TValue
.
using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;
namespace SystemTextJsonSamples
{
public class DictionaryTKeyEnumTValueConverter : JsonConverterFactory
{
public override bool CanConvert(Type typeToConvert)
{
if (!typeToConvert.IsGenericType)
{
return false;
}
if (typeToConvert.GetGenericTypeDefinition() != typeof(Dictionary<,>))
{
return false;
}
return typeToConvert.GetGenericArguments()[0].IsEnum;
}
public override JsonConverter CreateConverter(
Type type,
JsonSerializerOptions options)
{
Type[] typeArguments = type.GetGenericArguments();
Type keyType = typeArguments[0];
Type valueType = typeArguments[1];
JsonConverter converter = (JsonConverter)Activator.CreateInstance(
typeof(DictionaryEnumConverterInner<,>).MakeGenericType(
[keyType, valueType]),
BindingFlags.Instance | BindingFlags.Public,
binder: null,
args: [options],
culture: null)!;
return converter;
}
private class DictionaryEnumConverterInner<TKey, TValue> :
JsonConverter<Dictionary<TKey, TValue>> where TKey : struct, Enum
{
private readonly JsonConverter<TValue> _valueConverter;
private readonly Type _keyType;
private readonly Type _valueType;
public DictionaryEnumConverterInner(JsonSerializerOptions options)
{
// For performance, use the existing converter.
_valueConverter = (JsonConverter<TValue>)options
.GetConverter(typeof(TValue));
// Cache the key and value types.
_keyType = typeof(TKey);
_valueType = typeof(TValue);
}
public override Dictionary<TKey, TValue> Read(
ref Utf8JsonReader reader,
Type typeToConvert,
JsonSerializerOptions options)
{
if (reader.TokenType != JsonTokenType.StartObject)
{
throw new JsonException();
}
var dictionary = new Dictionary<TKey, TValue>();
while (reader.Read())
{
if (reader.TokenType == JsonTokenType.EndObject)
{
return dictionary;
}
// Get the key.
if (reader.TokenType != JsonTokenType.PropertyName)
{
throw new JsonException();
}
string? propertyName = reader.GetString();
// For performance, parse with ignoreCase:false first.
if (!Enum.TryParse(propertyName, ignoreCase: false, out TKey key) &&
!Enum.TryParse(propertyName, ignoreCase: true, out key))
{
throw new JsonException(
$"Unable to convert \"{propertyName}\" to Enum \"{_keyType}\".");
}
// Get the value.
reader.Read();
TValue value = _valueConverter.Read(ref reader, _valueType, options)!;
// Add to dictionary.
dictionary.Add(key, value);
}
throw new JsonException();
}
public override void Write(
Utf8JsonWriter writer,
Dictionary<TKey, TValue> dictionary,
JsonSerializerOptions options)
{
writer.WriteStartObject();
foreach ((TKey key, TValue value) in dictionary)
{
string propertyName = key.ToString();
writer.WritePropertyName
(options.PropertyNamingPolicy?.ConvertName(propertyName) ?? propertyName);
_valueConverter.Write(writer, value, options);
}
writer.WriteEndObject();
}
}
}
}
Steps to follow the basic pattern
The following steps explain how to create a converter by following the basic pattern:
- Create a class that derives from JsonConverter<T> where
T
is the type to be serialized and deserialized. - Override the
Read
method to deserialize the incoming JSON and convert it to typeT
. Use the Utf8JsonReader that's passed to the method to read the JSON. You don't have to worry about handling partial data, as the serializer passes all the data for the current JSON scope. So it isn't necessary to call Skip or TrySkip or to validate that Read returnstrue
. - Override the
Write
method to serialize the incoming object of typeT
. Use the Utf8JsonWriter that is passed to the method to write the JSON. - Override the
CanConvert
method only if necessary. The default implementation returnstrue
when the type to convert is of typeT
. Therefore, converters that support only typeT
don't need to override this method. For an example of a converter that does need to override this method, see the polymorphic deserialization section later in this article.
You can refer to the built-in converters source code as reference implementations for writing custom converters.
Steps to follow the factory pattern
The following steps explain how to create a converter by following the factory pattern:
- Create a class that derives from JsonConverterFactory.
- Override the
CanConvert
method to returntrue
when the type to convert is one that the converter can handle. For example, if the converter is forList<T>
, it might only handleList<int>
,List<string>
, andList<DateTime>
. - Override the
CreateConverter
method to return an instance of a converter class that will handle the type-to-convert that is provided at run time. - Create the converter class that the
CreateConverter
method instantiates.
The factory pattern is required for open generics because the code to convert an object to and from a string isn't the same for all types. A converter for an open generic type (List<T>
, for example) has to create a converter for a closed generic type (List<DateTime>
, for example) behind the scenes. Code must be written to handle each closed-generic type that the converter can handle.
The Enum
type is similar to an open generic type: a converter for Enum
has to create a converter for a specific Enum
(WeekdaysEnum
, for example) behind the scenes.
The use of Utf8JsonReader
in the Read
method
If your converter is converting a JSON object, the Utf8JsonReader
will be positioned on the begin object token when the Read
method begins. You must then read through all the tokens in that object and exit the method with the reader positioned on the corresponding end object token. If you read beyond the end of the object, or if you stop before reaching the corresponding end token, you get a JsonException
exception indicating that:
The converter 'ConverterName' read too much or not enough.
For an example, see the preceding factory pattern sample converter. The Read
method starts by verifying that the reader is positioned on a start object token. It reads until it finds that it is positioned on the next end object token. It stops on the next end object token because there are no intervening start object tokens that would indicate an object within the object. The same rule about begin token and end token applies if you are converting an array. For an example, see the Stack<T>
sample converter later in this article.
Error handling
The serializer provides special handling for exception types JsonException and NotSupportedException.
JsonException
If you throw a JsonException
without a message, the serializer creates a message that includes the path to the part of the JSON that caused the error. For example, the statement throw new JsonException()
produces an error message like the following example:
Unhandled exception. System.Text.Json.JsonException:
The JSON value could not be converted to System.Object.
Path: $.Date | LineNumber: 1 | BytePositionInLine: 37.
If you do provide a message (for example, throw new JsonException("Error occurred")
), the serializer still sets the Path, LineNumber, and BytePositionInLine properties.
NotSupportedException
If you throw a NotSupportedException
, you always get the path information in the message. If you provide a message, the path information is appended to it. For example, the statement throw new NotSupportedException("Error occurred.")
produces an error message like the following example:
Error occurred. The unsupported member type is located on type
'System.Collections.Generic.Dictionary`2[Samples.SummaryWords,System.Int32]'.
Path: $.TemperatureRanges | LineNumber: 4 | BytePositionInLine: 24
When to throw which exception type
When the JSON payload contains tokens that are not valid for the type being deserialized, throw a JsonException
.
When you want to disallow certain types, throw a NotSupportedException
. This exception is what the serializer automatically throws for types that are not supported. For example, System.Type
is not supported for security reasons, so an attempt to deserialize it results in a NotSupportedException
.
You can throw other exceptions as needed, but they don't automatically include JSON path information.
Register a custom converter
Register a custom converter to make the Serialize
and Deserialize
methods use it. Choose one of the following approaches:
- Add an instance of the converter class to the JsonSerializerOptions.Converters collection.
- Apply the [JsonConverter] attribute to the properties that require the custom converter.
- Apply the [JsonConverter] attribute to a class or a struct that represents a custom value type.
Registration sample - Converters collection
Here's an example that makes the DateTimeOffsetJsonConverter the default for properties of type DateTimeOffset:
var serializeOptions = new JsonSerializerOptions
{
WriteIndented = true,
Converters =
{
new DateTimeOffsetJsonConverter()
}
};
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);
Suppose you serialize an instance of the following type:
public class WeatherForecast
{
public DateTimeOffset Date { get; set; }
public int TemperatureCelsius { get; set; }
public string? Summary { get; set; }
}
Here's an example of JSON output that shows the custom converter was used:
{
"Date": "08/01/2019",
"TemperatureCelsius": 25,
"Summary": "Hot"
}
The following code uses the same approach to deserialize using the custom DateTimeOffset
converter:
var deserializeOptions = new JsonSerializerOptions();
deserializeOptions.Converters.Add(new DateTimeOffsetJsonConverter());
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString, deserializeOptions)!;
Registration sample - [JsonConverter] on a property
The following code selects a custom converter for the Date
property:
public class WeatherForecastWithConverterAttribute
{
[JsonConverter(typeof(DateTimeOffsetJsonConverter))]
public DateTimeOffset Date { get; set; }
public int TemperatureCelsius { get; set; }
public string? Summary { get; set; }
}
The code to serialize WeatherForecastWithConverterAttribute
doesn't require the use of JsonSerializeOptions.Converters
:
var serializeOptions = new JsonSerializerOptions
{
WriteIndented = true
};
jsonString = JsonSerializer.Serialize(weatherForecast, serializeOptions);
The code to deserialize also doesn't require the use of Converters
:
weatherForecast = JsonSerializer.Deserialize<WeatherForecastWithConverterAttribute>(jsonString)!;
Registration sample - [JsonConverter] on a type
Here's code that creates a struct and applies the [JsonConverter]
attribute to it:
using System.Text.Json.Serialization;
namespace SystemTextJsonSamples
{
[JsonConverter(typeof(TemperatureConverter))]
public struct Temperature
{
public Temperature(int degrees, bool celsius)
{
Degrees = degrees;
IsCelsius = celsius;
}
public int Degrees { get; }
public bool IsCelsius { get; }
public bool IsFahrenheit => !IsCelsius;
public override string ToString() =>
$"{Degrees}{(IsCelsius ? "C" : "F")}";
public static Temperature Parse(string input)
{
int degrees = int.Parse(input.Substring(0, input.Length - 1));
bool celsius = input.Substring(input.Length - 1) == "C";
return new Temperature(degrees, celsius);
}
}
}
Here's the custom converter for the preceding struct:
using System.Text.Json;
using System.Text.Json.Serialization;
namespace SystemTextJsonSamples
{
public class TemperatureConverter : JsonConverter<Temperature>
{
public override Temperature Read(
ref Utf8JsonReader reader,
Type typeToConvert,
JsonSerializerOptions options) =>
Temperature.Parse(reader.GetString()!);
public override void Write(
Utf8JsonWriter writer,
Temperature temperature,
JsonSerializerOptions options) =>
writer.WriteStringValue(temperature.ToString());
}
}
The [JsonConverter]
attribute on the struct registers the custom converter as the default for properties of type Temperature
. The converter is automatically used on the TemperatureCelsius
property of the following type when you serialize or deserialize it:
public class WeatherForecastWithTemperatureStruct
{
public DateTimeOffset Date { get; set; }
public Temperature TemperatureCelsius { get; set; }
public string? Summary { get; set; }
}
Converter registration precedence
During serialization or deserialization, a converter is chosen for each JSON element in the following order, listed from highest priority to lowest:
[JsonConverter]
applied to a property.- A converter added to the
Converters
collection. [JsonConverter]
applied to a custom value type or POCO.
If multiple custom converters for a type are registered in the Converters
collection, the first converter that returns true
for CanConvert
is used.
A built-in converter is chosen only if no applicable custom converter is registered.
Converter samples for common scenarios
The following sections provide converter samples that address some common scenarios that built-in functionality doesn't handle.
For a sample DataTable converter, see Supported collection types.
Deserialize inferred types to object properties
When deserializing to a property of type object
, a JsonElement
object is created. The reason is that the deserializer doesn't know what CLR type to create, and it doesn't try to guess. For example, if a JSON property has "true", the deserializer doesn't infer that the value is a Boolean
, and if an element has "01/01/2019", the deserializer doesn't infer that it's a DateTime
.
Type inference can be inaccurate. If the deserializer parses a JSON number that has no decimal point as a long
, that might result in out-of-range issues if the value was originally serialized as a ulong
or BigInteger
. Parsing a number that has a decimal point as a double
might lose precision if the number was originally serialized as a decimal
.
For scenarios that require type inference, the following code shows a custom converter for object
properties. The code converts:
true
andfalse
toBoolean
- Numbers without a decimal to
long
- Numbers with a decimal to
double
- Dates to
DateTime
- Strings to
string
- Everything else to
JsonElement
using System.Text.Json;
using System.Text.Json.Serialization;
namespace CustomConverterInferredTypesToObject
{
public class ObjectToInferredTypesConverter : JsonConverter<object>
{
public override object Read(
ref Utf8JsonReader reader,
Type typeToConvert,
JsonSerializerOptions options) => reader.TokenType switch
{
JsonTokenType.True => true,
JsonTokenType.False => false,
JsonTokenType.Number when reader.TryGetInt64(out long l) => l,
JsonTokenType.Number => reader.GetDouble(),
JsonTokenType.String when reader.TryGetDateTime(out DateTime datetime) => datetime,
JsonTokenType.String => reader.GetString()!,
_ => JsonDocument.ParseValue(ref reader).RootElement.Clone()
};
public override void Write(
Utf8JsonWriter writer,
object objectToWrite,
JsonSerializerOptions options) =>
JsonSerializer.Serialize(writer, objectToWrite, objectToWrite.GetType(), options);
}
public class WeatherForecast
{
public object? Date { get; set; }
public object? TemperatureCelsius { get; set; }
public object? Summary { get; set; }
}
public class Program
{
public static void Main()
{
string jsonString = """
{
"Date": "2019-08-01T00:00:00-07:00",
"TemperatureCelsius": 25,
"Summary": "Hot"
}
""";
WeatherForecast weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString)!;
Console.WriteLine($"Type of Date property no converter = {weatherForecast.Date!.GetType()}");
var options = new JsonSerializerOptions();
options.WriteIndented = true;
options.Converters.Add(new ObjectToInferredTypesConverter());
weatherForecast = JsonSerializer.Deserialize<WeatherForecast>(jsonString, options)!;
Console.WriteLine($"Type of Date property with converter = {weatherForecast.Date!.GetType()}");
Console.WriteLine(JsonSerializer.Serialize(weatherForecast, options));
}
}
}
// Produces output like the following example:
//
//Type of Date property no converter = System.Text.Json.JsonElement
//Type of Date property with converter = System.DateTime
//{
// "Date": "2019-08-01T00:00:00-07:00",
// "TemperatureCelsius": 25,
// "Summary": "Hot"
//}
The example shows the converter code and a WeatherForecast
class with object
properties. The Main
method deserializes a JSON string into a WeatherForecast
instance, first without using the converter, and then using the converter. The console output shows that without the converter, the run-time type for the Date
property is JsonElement
; with the converter, the run-time type is DateTime
.
The unit tests folder in the System.Text.Json.Serialization
namespace has more examples of custom converters that handle deserialization to object
properties.
Support polymorphic deserialization
.NET 7 provides support for both polymorphic serialization and deserialization. However, in previous .NET versions, there was limited polymorphic serialization support and no support for deserialization. If you're using .NET 6 or an earlier version, deserialization requires a custom converter.
Suppose, for example, you have a Person
abstract base class, with Employee
and Customer
derived classes. Polymorphic deserialization means that at design time you can specify Person
as the deserialization target, and Customer
and Employee
objects in the JSON are correctly deserialized at run time. During deserialization, you have to find clues that identify the required type in the JSON. The kinds of clues available vary with each scenario. For example, a discriminator property might be available or you might have to rely on the presence or absence of a particular property. The current release of System.Text.Json
doesn't provide attributes to specify how to handle polymorphic deserialization scenarios, so custom converters are required.
The following code shows a base class, two derived classes, and a custom converter for them. The converter uses a discriminator property to do polymorphic deserialization. The type discriminator isn't in the class definitions but is created during serialization and is read during deserialization.
Important
The example code requires JSON object name/value pairs to stay in order, which is not a standard requirement of JSON.
public class Person
{
public string? Name { get; set; }
}
public class Customer : Person
{
public decimal CreditLimit { get; set; }
}
public class Employee : Person
{
public string? OfficeNumber { get; set; }
}
using System.Text.Json;
using System.Text.Json.Serialization;
namespace SystemTextJsonSamples
{
public class PersonConverterWithTypeDiscriminator : JsonConverter<Person>
{
enum TypeDiscriminator
{
Customer = 1,
Employee = 2
}
public override bool CanConvert(Type typeToConvert) =>
typeof(Person).IsAssignableFrom(typeToConvert);
public override Person Read(
ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
if (reader.TokenType != JsonTokenType.StartObject)
{
throw new JsonException();
}
reader.Read();
if (reader.TokenType != JsonTokenType.PropertyName)
{
throw new JsonException();
}
string? propertyName = reader.GetString();
if (propertyName != "TypeDiscriminator")
{
throw new JsonException();
}
reader.Read();
if (reader.TokenType != JsonTokenType.Number)
{
throw new JsonException();
}
TypeDiscriminator typeDiscriminator = (TypeDiscriminator)reader.GetInt32();
Person person = typeDiscriminator switch
{
TypeDiscriminator.Customer => new Customer(),
TypeDiscriminator.Employee => new Employee(),
_ => throw new JsonException()
};
while (reader.Read())
{
if (reader.TokenType == JsonTokenType.EndObject)
{
return person;
}
if (reader.TokenType == JsonTokenType.PropertyName)
{
propertyName = reader.GetString();
reader.Read();
switch (propertyName)
{
case "CreditLimit":
decimal creditLimit = reader.GetDecimal();
((Customer)person).CreditLimit = creditLimit;
break;
case "OfficeNumber":
string? officeNumber = reader.GetString();
((Employee)person).OfficeNumber = officeNumber;
break;
case "Name":
string? name = reader.GetString();
person.Name = name;
break;
}
}
}
throw new JsonException();
}
public override void Write(
Utf8JsonWriter writer, Person person, JsonSerializerOptions options)
{
writer.WriteStartObject();
if (person is Customer customer)
{
writer.WriteNumber("TypeDiscriminator", (int)TypeDiscriminator.Customer);
writer.WriteNumber("CreditLimit", customer.CreditLimit);
}
else if (person is Employee employee)
{
writer.WriteNumber("TypeDiscriminator", (int)TypeDiscriminator.Employee);
writer.WriteString("OfficeNumber", employee.OfficeNumber);
}
writer.WriteString("Name", person.Name);
writer.WriteEndObject();
}
}
}
The following code registers the converter:
var serializeOptions = new JsonSerializerOptions();
serializeOptions.Converters.Add(new PersonConverterWithTypeDiscriminator());
The converter can deserialize JSON that was created by using the same converter to serialize, for example:
[
{
"TypeDiscriminator": 1,
"CreditLimit": 10000,
"Name": "John"
},
{
"TypeDiscriminator": 2,
"OfficeNumber": "555-1234",
"Name": "Nancy"
}
]
The converter code in the preceding example reads and writes each property manually. An alternative is to call Deserialize
or Serialize
to do some of the work. For an example, see this StackOverflow post.
An alternative way to do polymorphic deserialization
You can call Deserialize
in the Read
method:
- Make a clone of the
Utf8JsonReader
instance. SinceUtf8JsonReader
is a struct, this just requires an assignment statement. - Use the clone to read through the discriminator tokens.
- Call
Deserialize
using the originalReader
instance once you know the type you need. You can callDeserialize
because the originalReader
instance is still positioned to read the begin object token.
A disadvantage of this method is you can't pass in the original options instance that registers the converter to Deserialize
. Doing so would cause a stack overflow, as explained in Required properties. The following example shows a Read
method that uses this alternative:
public override Person Read(
ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
Utf8JsonReader readerClone = reader;
if (readerClone.TokenType != JsonTokenType.StartObject)
{
throw new JsonException();
}
readerClone.Read();
if (readerClone.TokenType != JsonTokenType.PropertyName)
{
throw new JsonException();
}
string? propertyName = readerClone.GetString();
if (propertyName != "TypeDiscriminator")
{
throw new JsonException();
}
readerClone.Read();
if (readerClone.TokenType != JsonTokenType.Number)
{
throw new JsonException();
}
TypeDiscriminator typeDiscriminator = (TypeDiscriminator)readerClone.GetInt32();
Person person = typeDiscriminator switch
{
TypeDiscriminator.Customer => JsonSerializer.Deserialize<Customer>(ref reader)!,
TypeDiscriminator.Employee => JsonSerializer.Deserialize<Employee>(ref reader)!,
_ => throw new JsonException()
};
return person;
}
Support round trip for Stack
types
If you deserialize a JSON string into a Stack
object and then serialize that object, the contents of the stack are in reverse order. This behavior applies to the following types and interfaces, and user-defined types that derive from them:
To support serialization and deserialization that retains the original order in the stack, a custom converter is required.
The following code shows a custom converter that enables round-tripping to and from Stack<T>
objects:
using System.Diagnostics;
using System.Reflection;
using System.Text.Json;
using System.Text.Json.Serialization;
namespace SystemTextJsonSamples
{
public class JsonConverterFactoryForStackOfT : JsonConverterFactory
{
public override bool CanConvert(Type typeToConvert)
=> typeToConvert.IsGenericType
&& typeToConvert.GetGenericTypeDefinition() == typeof(Stack<>);
public override JsonConverter CreateConverter(
Type typeToConvert, JsonSerializerOptions options)
{
Debug.Assert(typeToConvert.IsGenericType &&
typeToConvert.GetGenericTypeDefinition() == typeof(Stack<>));
Type elementType = typeToConvert.GetGenericArguments()[0];
JsonConverter converter = (JsonConverter)Activator.CreateInstance(
typeof(JsonConverterForStackOfT<>)
.MakeGenericType(new Type[] { elementType }),
BindingFlags.Instance | BindingFlags.Public,
binder: null,
args: null,
culture: null)!;
return converter;
}
}
public class JsonConverterForStackOfT<T> : JsonConverter<Stack<T>>
{
public override Stack<T> Read(
ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
if (reader.TokenType != JsonTokenType.StartArray)
{
throw new JsonException();
}
reader.Read();
var elements = new Stack<T>();
while (reader.TokenType != JsonTokenType.EndArray)
{
elements.Push(JsonSerializer.Deserialize<T>(ref reader, options)!);
reader.Read();
}
return elements;
}
public override void Write(
Utf8JsonWriter writer, Stack<T> value, JsonSerializerOptions options)
{
writer.WriteStartArray();
var reversed = new Stack<T>(value);
foreach (T item in reversed)
{
JsonSerializer.Serialize(writer, item, options);
}
writer.WriteEndArray();
}
}
}
The following code registers the converter:
var options = new JsonSerializerOptions
{
Converters = { new JsonConverterFactoryForStackOfT() },
};
Naming policies for enum string deserialization
By default, the built-in JsonStringEnumConverter can serialize and deserialize string values for enums. It works without a specified naming policy or with the CamelCase naming policy. It doesn't support other naming policies, such as snake case. For information about custom converter code that can support round-tripping to and from enum string values while using a snake case naming policy, see GitHub issue dotnet/runtime #31619. Alternatively, upgrade to .NET 7 or later versions, which provide built-in support for applying naming policies when round-tripping to and from enum string values.
Use default system converter
In some scenarios, you might want to use the default system converter in a custom converter. To do that, get the system converter from the JsonSerializerOptions.Default property, as shown in the following example:
public class MyCustomConverter : JsonConverter<int>
{
private readonly static JsonConverter<int> s_defaultConverter =
(JsonConverter<int>)JsonSerializerOptions.Default.GetConverter(typeof(int));
// Custom serialization logic
public override void Write(
Utf8JsonWriter writer, int value, JsonSerializerOptions options)
{
writer.WriteStringValue(value.ToString());
}
// Fall back to default deserialization logic
public override int Read(
ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
return s_defaultConverter.Read(ref reader, typeToConvert, options);
}
}
Handle null values
By default, the serializer handles null values as follows:
For reference types and Nullable<T> types:
- It does not pass
null
to custom converters on serialization. - It does not pass
JsonTokenType.Null
to custom converters on deserialization. - It returns a
null
instance on deserialization. - It writes
null
directly with the writer on serialization.
- It does not pass
For non-nullable value types:
- It passes
JsonTokenType.Null
to custom converters on deserialization. (If no custom converter is available, aJsonException
exception is thrown by the internal converter for the type.)
- It passes
This null-handling behavior is primarily to optimize performance by skipping an extra call to the converter. In addition, it avoids forcing converters for nullable types to check for null
at the start of every Read
and Write
method override.
To enable a custom converter to handle null
for a reference or value type, override JsonConverter<T>.HandleNull to return true
, as shown in the following example:
using System.Text.Json;
using System.Text.Json.Serialization;
namespace CustomConverterHandleNull
{
public class Point
{
public int X { get; set; }
public int Y { get; set; }
[JsonConverter(typeof(DescriptionConverter))]
public string? Description { get; set; }
}
public class DescriptionConverter : JsonConverter<string>
{
public override bool HandleNull => true;
public override string Read(
ref Utf8JsonReader reader,
Type typeToConvert,
JsonSerializerOptions options) =>
reader.GetString() ?? "No description provided.";
public override void Write(
Utf8JsonWriter writer,
string value,
JsonSerializerOptions options) =>
writer.WriteStringValue(value);
}
public class Program
{
public static void Main()
{
string json = @"{""x"":1,""y"":2,""Description"":null}";
Point point = JsonSerializer.Deserialize<Point>(json)!;
Console.WriteLine($"Description: {point.Description}");
}
}
}
// Produces output like the following example:
//
//Description: No description provided.
Preserve references
By default, reference data is only cached for each call to Serialize or Deserialize. To persist references from one Serialize
/Deserialize
call to another one, root the ReferenceResolver instance in the call site of Serialize
/Deserialize
. The following code shows an example for this scenario:
- You write a custom converter for the
Company
type. - You don't want to manually serialize the
Supervisor
property, which is anEmployee
. You want to delegate that to the serializer and you also want to preserve the references that you have already saved.
Here are the Employee
and Company
classes:
public class Employee
{
public string? Name { get; set; }
public Employee? Manager { get; set; }
public List<Employee>? DirectReports { get; set; }
public Company? Company { get; set; }
}
public class Company
{
public string? Name { get; set; }
public Employee? Supervisor { get; set; }
}
The converter looks like this:
class CompanyConverter : JsonConverter<Company>
{
public override Company Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
throw new NotImplementedException();
}
public override void Write(Utf8JsonWriter writer, Company value, JsonSerializerOptions options)
{
writer.WriteStartObject();
writer.WriteString("Name", value.Name);
writer.WritePropertyName("Supervisor");
JsonSerializer.Serialize(writer, value.Supervisor, options);
writer.WriteEndObject();
}
}
A class that derives from ReferenceResolver stores the references in a dictionary:
class MyReferenceResolver : ReferenceResolver
{
private uint _referenceCount;
private readonly Dictionary<string, object> _referenceIdToObjectMap = new ();
private readonly Dictionary<object, string> _objectToReferenceIdMap = new (ReferenceEqualityComparer.Instance);
public override void AddReference(string referenceId, object value)
{
if (!_referenceIdToObjectMap.TryAdd(referenceId, value))
{
throw new JsonException();
}
}
public override string GetReference(object value, out bool alreadyExists)
{
if (_objectToReferenceIdMap.TryGetValue(value, out string? referenceId))
{
alreadyExists = true;
}
else
{
_referenceCount++;
referenceId = _referenceCount.ToString();
_objectToReferenceIdMap.Add(value, referenceId);
alreadyExists = false;
}
return referenceId;
}
public override object ResolveReference(string referenceId)
{
if (!_referenceIdToObjectMap.TryGetValue(referenceId, out object? value))
{
throw new JsonException();
}
return value;
}
}
A class that derives from ReferenceHandler holds an instance of MyReferenceResolver
and creates a new instance only when needed (in a method named Reset
in this example):
class MyReferenceHandler : ReferenceHandler
{
public MyReferenceHandler() => Reset();
private ReferenceResolver? _rootedResolver;
public override ReferenceResolver CreateResolver() => _rootedResolver!;
public void Reset() => _rootedResolver = new MyReferenceResolver();
}
When the sample code calls the serializer, it uses a JsonSerializerOptions instance in which the ReferenceHandler property is set to an instance of MyReferenceHandler
. When you follow this pattern, be sure to reset the ReferenceResolver
dictionary when you're finished serializing, to keep it from growing forever.
var options = new JsonSerializerOptions();
options.Converters.Add(new CompanyConverter());
var myReferenceHandler = new MyReferenceHandler();
options.ReferenceHandler = myReferenceHandler;
options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
options.WriteIndented = true;
string str = JsonSerializer.Serialize(tyler, options);
// Reset after serializing to avoid out of bounds memory growth in the resolver.
myReferenceHandler.Reset();
The preceding example only does serialization, but a similar approach can be adopted for deserialization.
Other custom converter samples
The Migrate from Newtonsoft.Json to System.Text.Json article contains additional samples of custom converters.
The unit tests folder in the System.Text.Json.Serialization
source code includes other custom converter samples, such as:
- Int32 converter that converts null to 0 on deserialize
- Int32 converter that allows both string and number values on deserialize
- Enum converter
- List<T> converter that accepts external data
- Long[] converter that works with a comma-delimited list of numbers
If you need to make a converter that modifies the behavior of an existing built-in converter, you can get the source code of the existing converter to serve as a starting point for customization.
Additional resources
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for