Plinth.Serialization 1.8.0

README

Plinth.Serialization

Serialization utilities for JSON and XML

Provides utilities for JSON and XML serialization with sensible defaults and custom converters.

Components

• JsonUtil - Wrapper over Newtonsoft.Json with Plinth standard JSON serialization
• XmlUtil - Shortcut methods for XML serialization
• JsonNet Converters - Custom converters and contract resolvers for Newtonsoft.Json
• UtcDateTimeConverter - System.ComponentModel.DateTimeConverter for ensuring all deserialized dates are UTC

JsonUtil

JsonUtil provides a simplified API for JSON serialization with Plinth's default settings:

• Ignores null values during serialization
• Handles nullable enums as strings
• Parses floating-point numbers as decimals for precision

Basic Serialization

using Plinth.Serialization;

public class User
{
    public Guid Id { get; set; }
    public string Name { get; set; }
    public string? Email { get; set; }
}

var user = new User { Id = Guid.NewGuid(), Name = "John Doe" };

// Serialize to JSON string
var json = JsonUtil.SerializeObject(user);
// Result: {"Id":"...","Name":"John Doe"}
// Note: Email is null and not included in output

// Deserialize from JSON string
var deserializedUser = JsonUtil.DeserializeObject<User>(json);

File Operations

// Deserialize from file
var config = JsonUtil.DeserializeObjectFromFile<AppConfig>("config.json");

// Try deserialize with error handling
if (JsonUtil.TryDeserializeObjectFromFile<AppConfig>("config.json", out var result))
{
    // Use result
}
else
{
    // Handle failure
}

Custom Settings

You can customize serialization settings for specific calls:

var json = JsonUtil.SerializeObject(user, settings =>
{
    settings.Formatting = Newtonsoft.Json.Formatting.Indented;
    settings.NullValueHandling = Newtonsoft.Json.NullValueHandling.Include;
});

Deep Cloning

// Create a deep clone using JSON serialization
var userCopy = JsonUtil.DeepClone(user);

Converting Deserialized Objects

Useful when working with dynamic JSON:

// Convert deserialized object to specific type
var obj = JsonUtil.DeserializeObject<object>(json);
var userId = JsonUtil.ConvertDeserializedObject<Guid>(obj, Guid.Empty);

// Try convert with null check
if (JsonUtil.TryConvertDeserializedObject<Guid>(obj, out var id))
{
    // Use id
}

XmlUtil

XmlUtil provides utilities for XML serialization using .NET's XmlSerializer.

Basic Serialization

using Plinth.Serialization;

public class Book
{
    public string Title { get; set; }
    public string Author { get; set; }
    public int Year { get; set; }
}

var book = new Book
{
    Title = "Sample Book",
    Author = "John Doe",
    Year = 2024
};

// Serialize to XML string with default settings (includes namespaces, declaration, indented)
var xml = XmlUtil.Serialize(book);

// Serialize with custom settings
var xml = XmlUtil.Serialize(book,
    XmlUtil.SerializerSettings.OmitNamespaces |
    XmlUtil.SerializerSettings.OmitXmlDeclaration);

Serializer Settings

Available flags:

• Default - Includes namespaces, XML declaration, and indentation
• OmitNamespaces - Excludes XML namespaces from output
• OmitXmlDeclaration - Excludes <?xml version="1.0"?> declaration
• NoIndent - Outputs XML without indentation

Deserialization

// Deserialize from XML string
var book = XmlUtil.Deserialize<Book>(xml);

// Deserialize from file
var book = XmlUtil.DeserializeFromFile<Book>("book.xml");

// Deserialize from stream
using var stream = File.OpenRead("book.xml");
var book = XmlUtil.DeserializeFromStream<Book>(stream);

Stream Serialization

// Serialize to stream (useful for large files or network streams)
using var stream = File.Create("output.xml");
XmlUtil.Serialize(book, stream, XmlUtil.SerializerSettings.Default);

XML Validation

Validate XML against XSD schemas:

var xml = File.ReadAllText("data.xml");
var errors = XmlUtil.Validate(xml, "schema1.xsd", "schema2.xsd");

if (errors.Count == 0)
{
    Console.WriteLine("XML is valid");
}
else
{
    foreach (var error in errors)
    {
        Console.WriteLine($"Validation error: {error}");
    }
}

Custom Converters

JsonNetStringNullableEnumConverter

Automatically included in JsonUtil, this converter serializes nullable enums as strings instead of integers.

public enum Status { Active, Inactive, Pending }

public class Item
{
    public Status? CurrentStatus { get; set; }
}

// Serializes as: {"CurrentStatus":"Active"} instead of {"CurrentStatus":0}

Contract Resolvers

CamelCase Property Names:

using Plinth.Serialization.JsonNet;

var settings = new JsonSerializerSettings
{
    ContractResolver = new JsonNetCamelCasePropertyNamesContractResolver()
};

// Properties like "FirstName" will serialize as "firstName"

Underscore Property Names:

using Plinth.Serialization.JsonNet;

var settings = new JsonSerializerSettings
{
    ContractResolver = new JsonNetUnderscorePropertyNamesContractResolver()
};

// Properties like "FirstName" will serialize as "first_name"

Best Practices

1. Use JsonUtil for Consistency - JsonUtil applies Plinth's standard settings across your application
2. Null Handling - Remember that JsonUtil ignores null values by default to reduce payload size
3. XML Namespaces - Use OmitNamespaces when namespaces aren't required for cleaner XML
4. File Operations - Use TryDeserialize methods for better error handling when reading files
5. Deep Cloning - Only use DeepClone for simple objects; complex object graphs may require custom cloning logic