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