In modern .NET, use System.Text.Json to serialize a dictionary to JSON and deserialize it back into a compatible dictionary type. The same pattern works with common dictionary interfaces and implementations; choose the matching key and value types when restoring the data.
Serialize and deserialize a dictionary with System.Text.Json
This example converts a Dictionary<string, int> to a JSON object, then restores it to the same dictionary type:
using System.Text.Json;
var values = new Dictionary<string, int>
{
["apples"] = 3,
["oranges"] = 5
};
string json = JsonSerializer.Serialize(values);
Dictionary<string, int>? restored =
JsonSerializer.Deserialize<Dictionary<string, int>>(json);The resulting JSON is {"apples":3,"oranges":5}. The type supplied to Deserialize should match the JSON values. For example, use Dictionary<string, int> when the values are integers. Microsoft documents support for generic dictionaries and common dictionary interfaces in both directions: supported types in System.Text.Json.
The example uses nullable reference type syntax on the result. Deserializing the JSON literal null can return null; otherwise the value must be compatible with the requested dictionary type.
#1 Best Overall
Which dictionary key types work?
JSON objects represent dictionary keys as property names, so keys must be convertible to and from property-name strings. System.Text.Json includes built-in conversion support for common key types, including:
string,bool, integral and floating-point numeric typesDateTimeandDateTimeOffset- Enums,
Guid,TimeSpan,Uri, andVersion
A key type outside the supported set needs a custom converter that implements WriteAsPropertyName and ReadAsPropertyName. See Microsoft’s documentation on supported types and dictionary-key conversion.
Change dictionary key names during serialization
Set JsonSerializerOptions.DictionaryKeyPolicy when you want serialized property names transformed, for example to apply a naming convention:
var options = new JsonSerializerOptions
{
DictionaryKeyPolicy = JsonNamingPolicy.CamelCase
};
string json = JsonSerializer.Serialize(values, options);The policy applies when writing dictionary keys. During deserialization, System.Text.Json reads the keys as they appear in the JSON rather than applying the naming policy to rewrite them. Microsoft’s property and value customization guidance documents this serialization-only behavior for dictionary-key naming policies.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteSpecial case: Dictionary<string, object>
With System.Text.Json, values in a Dictionary<string, object> deserialize as JsonElement by default. They are not automatically inferred as ordinary CLR primitives, JObject, or JArray. Code that needs a particular type should inspect or convert each element, or use a suitable custom converter.
Newtonsoft.Json behaves differently in this case: its migration comparison describes inference to CLR primitive values and to JObject or JArray for complex values. The difference matters when existing application code expects to cast values directly. See Microsoft’s migration guide.
Rank #4
Use Newtonsoft.Json when your application depends on it
Newtonsoft.Json can serialize and deserialize dictionaries with JsonConvert:
using Newtonsoft.Json;
string json = JsonConvert.SerializeObject(values);
Dictionary<string, int>? restored =
JsonConvert.DeserializeObject<Dictionary<string, int>>(json);| Consideration | System.Text.Json | Newtonsoft.Json |
|---|---|---|
| Availability | Built into the modern .NET stack as its JSON API. Microsoft overview | External library used by many existing applications; dictionary support is covered in Microsoft’s migration guide. |
| Dictionary support | Generic dictionaries and common interfaces are supported for serialization and deserialization. Supported types | Dictionary support is documented in Microsoft’s migration guide. |
Dictionary<string, object> values |
Deserialized values are JsonElement by default. |
Values are inferred as CLR primitives or as JObject and JArray for complex values. |
| String enum values | Require an appropriate enum converter by default. | Supported by default in the migration comparison. |
| Custom key types | Use a converter with property-name read and write methods. | Use a converter or suitable key configuration for the type. |
For a new application, System.Text.Json is a straightforward first choice when its defaults and converter model meet the requirements. Keep Newtonsoft.Json when existing converters, object-value inference, or other established behavior is part of the application contract. Check the APIs and options available in the project’s target .NET framework; source-generation and AOT guidance can vary by release.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Errors to check when deserialization fails
JsonException: The input may be invalid JSON, incompatible with the requested target type, or contain non-whitespace data after a JSON value.NotSupportedException: The serializer may lack a compatible converter, such as for an unsupported dictionary key type.
Microsoft lists these failure cases in the System.Text.Json converter guidance. Confirm that the payload’s keys and values match the types requested by Deserialize, and add a converter where a key type needs custom property-name handling.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
