.net deserialization cheat sheet

.NET Deserialization Cheat Sheet: Practical Guide for JSON & XML

This cheatsheet focuses on practical, modern, and secure deserialization in .NET, primarily using the recommended built-in System.Text.Json and the widely-used Newtonsoft.Json (Json.NET) library.

1. Modern JSON Deserialization (Recommended) 💡

Use the built-in library, System.Text.Json (part of the .NET framework since .NET Core 3.0), for superior performance and security by default.

Basic Usage

Key Configuration (JsonSerializerOptions)

Code Snippet (C#)

using System.Text.Json;

// Define your target DTO (Data Transfer Object)
public class UserData 
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public UserData DeserializeUser(string json)
{
    var options = new JsonSerializerOptions 
    { 
        PropertyNameCaseInsensitive = true 
    };

    try 
    {
        // Deserialization with safe, built-in features
        return JsonSerializer.Deserialize<UserData>(json, options);
    } 
    catch (JsonException ex) 
    {
        // Always handle malformed input
        throw new Exception("Invalid JSON format.", ex);
    }
}

2. Newtonsoft.Json (Json.NET) Deserialization

A highly feature-rich and flexible third-party library, common in older and complex projects.

Basic Usage

Key Configuration (JsonSerializerSettings)

3. XML Deserialization

Used for SOAP, configuration, and data-sharing scenarios where JSON isn’t used.

Basic Usage

XML Attributes

4. Security & Best Practices 🛡️

The #1 Rule: NEVER deserialize untrusted data with formatters that include type information.

Safely Deserializing a Stream (Json.NET)

Using a StreamReader and a JsonTextReader is safer for large or unknown-size payloads.

using Newtonsoft.Json;
using System.IO;

public MyClass SafeDeserialize(Stream stream)
{
    using (var reader = new StreamReader(stream))
    using (var jsonReader = new JsonTextReader(reader))
    {
        var serializer = new JsonSerializer 
        {
            // Enforce security best practice
            TypeNameHandling = TypeNameHandling.None 
        };
        return serializer.Deserialize<MyClass>(jsonReader);
    }
}

5. Advanced Customization & Annotations

Use C# attributes to customize the mapping between your class and the serialized data format.