C# Serialization

Introduction

Serialization is the process of converting objects into a format that can be easily stored or transmitted, and later reconstructed back into objects. In C#, this is a fundamental technique for saving application data, sharing information between systems, or transmitting objects over networks.

Think of serialization as packing your belongings into boxes when moving homes. You need to organize everything carefully so that you can unpack and restore them to their original state at your new home. Similarly, deserialization is the process of "unpacking" serialized data back into usable objects.

In this tutorial, we'll explore different types of serialization in C#:

JSON Serialization
XML Serialization
Binary Serialization

Why Use Serialization?

Before diving into the implementation, let's understand why serialization is important:

Data Persistence: Save application state between sessions
Data Transfer: Send objects over networks
Caching: Store complex objects in memory or disk cache
Deep Copying: Create exact copies of objects
Cross-platform Compatibility: Exchange data between different systems

Prerequisites

To follow along with this tutorial, you should have:

Basic understanding of C# classes and objects
Visual Studio or another C# development environment
.NET Core or .NET Framework installed

JSON Serialization

JSON (JavaScript Object Notation) is a lightweight, human-readable data format that's widely used for data exchange. The System.Text.Json namespace in modern .NET provides built-in JSON serialization capabilities.

Basic JSON Serialization

Let's start with a simple example:

csharp
using System;
using System.Text.Json;
using System.IO;

// Define a simple class to serialize
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
}

class Program
{
    static void Main(string[] args)
    {
        // Create a new Person object
        Person person = new Person
        {
            Name = "John Doe",
            Age = 30,
            Email = "[email protected]"
        };

        // Serialize the person object to JSON
        string jsonString = JsonSerializer.Serialize(person);
        
        // Display the JSON string
        Console.WriteLine("Serialized JSON:");
        Console.WriteLine(jsonString);
        
        // Save the JSON to a file
        File.WriteAllText("person.json", jsonString);
        Console.WriteLine("JSON saved to person.json");
        
        // Deserialize from JSON string back to object
        Person deserializedPerson = JsonSerializer.Deserialize<Person>(jsonString);
        
        // Verify deserialization worked
        Console.WriteLine("\nDeserialized Person:");
        Console.WriteLine($"Name: {deserializedPerson.Name}");
        Console.WriteLine($"Age: {deserializedPerson.Age}");
        Console.WriteLine($"Email: {deserializedPerson.Email}");
    }
}

Output:

Serialized JSON:
{"Name":"John Doe","Age":30,"Email":"[email protected]"}
JSON saved to person.json

Deserialized Person:
Name: John Doe
Age: 30
Email: [email protected]

Customizing JSON Serialization

You can customize JSON serialization using JsonSerializerOptions:

csharp
using System.Text.Json;
using System.Text.Json.Serialization;

// Create serialization options
JsonSerializerOptions options = new JsonSerializerOptions
{
    WriteIndented = true, // Makes the JSON output formatted with indentation
    PropertyNamingPolicy = JsonNamingPolicy.CamelCase, // Uses camelCase for property names
    DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull // Skip null values
};

// Serialize with options
string jsonFormatted = JsonSerializer.Serialize(person, options);
Console.WriteLine("Formatted JSON:");
Console.WriteLine(jsonFormatted);

Output:

Formatted JSON:
{
  "name": "John Doe",
  "age": 30,
  "email": "[email protected]"
}

Handling Complex Objects

For more complex objects, like those with nested classes or collections:

csharp
public class Address
{
    public string Street { get; set; }
    public string City { get; set; }
    public string ZipCode { get; set; }
}

public class Employee
{
    public string Name { get; set; }
    public int ID { get; set; }
    public Address HomeAddress { get; set; }
    public List<string> Skills { get; set; }
}

// Create and serialize a complex object
Employee employee = new Employee
{
    Name = "Jane Smith",
    ID = 12345,
    HomeAddress = new Address
    {
        Street = "123 Main St",
        City = "Anytown",
        ZipCode = "12345"
    },
    Skills = new List<string> { "C#", "JavaScript", "Database Design" }
};

string complexJson = JsonSerializer.Serialize(employee, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(complexJson);

Output:

{
  "Name": "Jane Smith",
  "ID": 12345,
  "HomeAddress": {
    "Street": "123 Main St",
    "City": "Anytown",
    "ZipCode": "12345"
  },
  "Skills": [
    "C#",
    "JavaScript",
    "Database Design"
  ]
}

XML Serialization

XML (eXtensible Markup Language) is another common format for data exchange. .NET provides XML serialization through the System.Xml.Serialization namespace.

Basic XML Serialization

csharp
using System;
using System.IO;
using System.Xml.Serialization;

// Class to serialize (must have a parameterless constructor)
public class Product
{
    // Default constructor required for XML serialization
    public Product() { }
    
    public Product(int id, string name, decimal price)
    {
        ProductId = id;
        ProductName = name;
        Price = price;
    }
    
    public int ProductId { get; set; }
    public string ProductName { get; set; }
    public decimal Price { get; set; }
}

class Program
{
    static void Main(string[] args)
    {
        // Create a product
        Product laptop = new Product(1001, "Laptop", 999.99m);
        
        // Create XML serializer
        XmlSerializer serializer = new XmlSerializer(typeof(Product));
        
        // Serialize to file
        using (TextWriter writer = new StreamWriter("product.xml"))
        {
            serializer.Serialize(writer, laptop);
        }
        
        Console.WriteLine("Product serialized to XML file.");
        
        // Display the XML content
        string xmlContent = File.ReadAllText("product.xml");
        Console.WriteLine("\nXML Content:");
        Console.WriteLine(xmlContent);
        
        // Deserialize from file
        Product deserializedProduct;
        using (FileStream fileStream = new FileStream("product.xml", FileMode.Open))
        {
            deserializedProduct = (Product)serializer.Deserialize(fileStream);
        }
        
        // Verify deserialization
        Console.WriteLine("\nDeserialized Product:");
        Console.WriteLine($"ID: {deserializedProduct.ProductId}");
        Console.WriteLine($"Name: {deserializedProduct.ProductName}");
        Console.WriteLine($"Price: ${deserializedProduct.Price}");
    }
}

Output:

Product serialized to XML file.

XML Content:
<?xml version="1.0" encoding="utf-8"?>
<Product xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <ProductId>1001</ProductId>
  <ProductName>Laptop</ProductName>
  <Price>999.99</Price>
</Product>

Deserialized Product:
ID: 1001
Name: Laptop
Price: $999.99

Customizing XML Serialization

You can customize XML serialization using attributes:

csharp
using System.Xml.Serialization;

[XmlRoot("ProductInfo")]
public class Product
{
    public Product() { }
    
    // Constructor remains the same
    
    [XmlElement("ID")]
    public int ProductId { get; set; }
    
    [XmlElement("Title")]
    public string ProductName { get; set; }
    
    [XmlElement("Cost")]
    public decimal Price { get; set; }
    
    [XmlIgnore] // This property will not be serialized
    public decimal DiscountedPrice { get; set; }
}

This will produce XML with custom element names and ignore specified properties.

Binary Serialization

Binary serialization converts objects to a binary format, which is more compact and faster than text-based formats like JSON or XML. It's less human-readable but more efficient.

Note: BinaryFormatter is obsolete in newer .NET versions due to security concerns. It's recommended to use other serialization formats or newer binary serialization libraries like MessagePack.

However, for educational purposes, here's how binary serialization works:

csharp
using System;
using System.IO;
using System.Runtime.Serialization.Formatters.Binary;

// Mark class as serializable
[Serializable]
public class GameState
{
    public string PlayerName { get; set; }
    public int Score { get; set; }
    public DateTime LastPlayed { get; set; }
    
    // Non-serializable field
    [NonSerialized]
    private readonly int temporaryData;
    
    public GameState()
    {
        temporaryData = new Random().Next(1000);
    }
}

class Program
{
    static void Main(string[] args)
    {
        // Create game state
        GameState game = new GameState
        {
            PlayerName = "Player1",
            Score = 5000,
            LastPlayed = DateTime.Now
        };
        
        // Create binary formatter
        BinaryFormatter formatter = new BinaryFormatter();
        
        // Serialize to file
        using (FileStream stream = new FileStream("gamestate.bin", FileMode.Create))
        {
            formatter.Serialize(stream, game);
        }
        
        Console.WriteLine("Game state saved to binary file.");
        
        // Deserialize from file
        GameState loadedGame;
        using (FileStream stream = new FileStream("gamestate.bin", FileMode.Open))
        {
            loadedGame = (GameState)formatter.Deserialize(stream);
        }
        
        // Verify deserialization
        Console.WriteLine("\nDeserialized Game State:");
        Console.WriteLine($"Player: {loadedGame.PlayerName}");
        Console.WriteLine($"Score: {loadedGame.Score}");
        Console.WriteLine($"Last Played: {loadedGame.LastPlayed}");
    }
}

Real-World Applications

1. Configuration Settings

Serialization is commonly used for saving application settings:

csharp
public class AppSettings
{
    public string Theme { get; set; }
    public bool NotificationsEnabled { get; set; }
    public Dictionary<string, string> UserPreferences { get; set; }
}

// Save settings
public static void SaveSettings(AppSettings settings, string filePath)
{
    string json = JsonSerializer.Serialize(settings, new JsonSerializerOptions { WriteIndented = true });
    File.WriteAllText(filePath, json);
}

// Load settings
public static AppSettings LoadSettings(string filePath)
{
    if (File.Exists(filePath))
    {
        string json = File.ReadAllText(filePath);
        return JsonSerializer.Deserialize<AppSettings>(json);
    }
    return new AppSettings(); // Return default settings if file doesn't exist
}

2. API Communication

Serialization is essential when working with web APIs:

csharp
using System.Net.Http;
using System.Net.Http.Json;
using System.Threading.Tasks;

public class WeatherForecast
{
    public DateTime Date { get; set; }
    public int TemperatureC { get; set; }
    public string Summary { get; set; }
}

public async Task<List<WeatherForecast>> GetWeatherForecastAsync()
{
    using HttpClient client = new HttpClient();
    // The API returns JSON that's automatically deserialized
    return await client.GetFromJsonAsync<List<WeatherForecast>>("https://api.example.com/weather");
}

public async Task PostNewForecastAsync(WeatherForecast forecast)
{
    using HttpClient client = new HttpClient();
    // Object is automatically serialized to JSON
    await client.PostAsJsonAsync("https://api.example.com/weather", forecast);
}

3. Data Caching

Serialization can help with caching expensive computations:

csharp
public class DataCache
{
    public static T GetOrCreate<T>(string key, Func<T> createItem) where T : class
    {
        string cachePath = Path.Combine(GetCacheDirectory(), $"{key}.cache");
        
        // Try to load from cache
        if (File.Exists(cachePath))
        {
            try
            {
                string json = File.ReadAllText(cachePath);
                return JsonSerializer.Deserialize<T>(json);
            }
            catch
            {
                // Cache read failed, continue to create new item
            }
        }
        
        // Create new item
        T item = createItem();
        
        // Save to cache
        try
        {
            string json = JsonSerializer.Serialize(item);
            File.WriteAllText(cachePath, json);
        }
        catch
        {
            // Cache write failed, but we can still return the item
        }
        
        return item;
    }
    
    private static string GetCacheDirectory()
    {
        string dir = Path.Combine(Path.GetTempPath(), "AppCache");
        Directory.CreateDirectory(dir);
        return dir;
    }
}

Best Practices

Choose the right format:
- JSON: For human-readable, cross-platform data exchange
- XML: When you need strict schema validation or work with legacy systems
- Binary: For better performance and storage efficiency (but consider security implications)
Handle versioning:
- Ensure your serialization can handle older versions of your classes
- Consider adding version properties to your serializable classes
Error handling:
- Always wrap serialization/deserialization in try-catch blocks
- Validate data after deserialization
Security:
- Never deserialize data from untrusted sources using BinaryFormatter
- Sanitize and validate data after deserialization
Performance:
- Cache serializers when possible
- For high-performance scenarios, consider specialized libraries like Protocol Buffers or MessagePack

Summary

In this tutorial, we've covered:

The concept of serialization and why it's important
JSON serialization using System.Text.Json
XML serialization using XmlSerializer
Binary serialization using BinaryFormatter (though noting its obsolescence)
Real-world applications and best practices

Serialization is a fundamental skill for C# developers. It enables data persistence, communication between systems, and various other important applications. By understanding these different serialization techniques, you can choose the best approach for your specific needs.

Additional Resources

Microsoft Documentation: JSON Serialization
Microsoft Documentation: XML Serialization
Newtonsoft.Json Library - A popular alternative JSON library

Exercises

Create a simple note-taking application that serializes notes to JSON files
Extend the Person class to include nested collections and complex properties, then serialize it
Create a program that converts between JSON and XML formats
Implement a settings manager that saves user preferences using serialization
Create a class that implements custom serialization logic using the ISerializable interface

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)

Introduction​

Why Use Serialization?​

Prerequisites​

JSON Serialization​

Basic JSON Serialization​

Customizing JSON Serialization​

Handling Complex Objects​

XML Serialization​

Basic XML Serialization​

Customizing XML Serialization​

Binary Serialization​

Real-World Applications​

1. Configuration Settings​

2. API Communication​

3. Data Caching​

Best Practices​

Summary​

Additional Resources​

Exercises​

Introduction

Why Use Serialization?

Prerequisites

JSON Serialization

Basic JSON Serialization

Customizing JSON Serialization

Handling Complex Objects

XML Serialization

Basic XML Serialization

Customizing XML Serialization

Binary Serialization

Real-World Applications

1. Configuration Settings

2. API Communication

3. Data Caching

Best Practices

Summary

Additional Resources

Exercises