Dennis198.DotSerial 3.1.0

DotSerial

DotSerial is a lightweight cross-platform C# library for serializing and deserializing .NET objects. It allows developers to easily mark properties for serialization using a simple attribute, and provides functionality to save and load objects from files in different data serialization formats.

If you encounter any errors, you can create an issue at GitHub.

Features

• Serialize and deserialize .NET objects to JSON, XML, YAML, and Toon
• Simple attribute-based customization with [DotSerialName] and [DotSerialIgnore]
• Save objects to a file and load them back
• Navigate and manipulate serialized data trees with the DSNode API
• Developer-friendly and lightweight

Installation

Add DotSerial to your project via NuGet. Or include the source in your project.

Usage

Define a class

using DotSerial.Attributes;

public class Example
{
    [DotSerialName("Example_Boolean")]
    public bool Boolean { get; set; }

    [DotSerialName("Example_Number")]
    public int Number { get; set; }

    [DotSerialName("Example_Text")]
    public string Text { get; set; }
}

Serialize and Deserialize with DSConverter

DSConverter provides static methods for converting objects to and from serialized strings and files. Use SerializeStrategy to choose the format.

using DotSerial;

var obj = new Example
{
    Boolean = true,
    Number = 42,
    Text = "Hello DotSerial!"
};

// Serialize to a JSON string
string json = DSConverter.Serialize(obj, SerializeStrategy.Json);
// {
//   "Example_Boolean": "true",
//   "Example_Number": "42",
//   "Example_Text": "Hello DotSerial!"
// }

// Deserialize back to an object
Example result = DSConverter.Deserialize<Example>(json, SerializeStrategy.Json);

// Serialize to TOON
string toon = DSConverter.Serialize(obj, SerializeStrategy.Toon);

// Deserialize from YAML
Example fromYaml = DSConverter.Deserialize<Example>(yamlString, SerializeStrategy.Yaml);

Save and Load from File

// Save to file
DSConverter.SaveToFile("example.json", obj, SerializeStrategy.Json);

// Load from file
Example loaded = DSConverter.LoadFromFile<Example>("example.json", SerializeStrategy.Json);

Working with DSNode

DSNode represents a node in the DotSerial document tree. It implements IDictionary<string, DSNode>, so you can navigate, read, and modify serialized data without mapping it to a class.

Parse a string into a node tree

DSNode root = DSNode.FromString(json, SerializeStrategy.Json);
// or via DSConverter:
DSNode root = DSConverter.ToNodeFromString(json, SerializeStrategy.Json);

Convert an object to a node tree

DSNode node = DSNode.ToNode(obj, SerializeStrategy.Json);
// or via DSConverter:
DSNode node = DSConverter.ToNode(obj, SerializeStrategy.Json);

Read node values

// Access a child by key
DSNode child = root["Example_Text"];

// Get the raw string value of a leaf node
string? value = child.GetNodeValue();

// Check the node type (Object, Value, or Array)
NodeType type = root.GetNodeType();

Modify nodes

// Set a leaf value (overloads for string, int, bool, double, DateTime, Guid, etc.)
child.SetNodeValue("Updated text");
child.SetNodeValue(100);
child.SetNodeValue(true);

// Add a new child node
DSNode newChild = DSNode.ToNode("new value", SerializeStrategy.Json, "NewKey");
root.Add("NewKey", newChild);

// Remove a child
root.Remove("Example_Number");

// Clear all children
root.Clear();

Iterate over children

foreach (var (key, childNode) in root)
{
    Console.WriteLine($"{key}: {childNode.GetNodeValue()}");
}

Serialize a node tree back to a string

string output = root.Stringify();

Deserialize a string directly into an object

Example obj = DSNode.ToObject<Example>(json, SerializeStrategy.Json);

Serialization Strategies

Use the SerializeStrategy enum to choose a format:

Attribute Reference

• [DotSerialName(string name)]
  • Assign a custom name to a property for serialization.
  • The name must be unique within the class.
  • Properties without this attribute use the property name as-is.
• [DotSerialIgnore]
  • Properties with this attribute are excluded from serialization.

[DotSerialName("User_Name")]
public string Name { get; set; }

[DotSerialName("User_Age")]
public int Age { get; set; }

public string Occupation { get; set; }

[DotSerialIgnore]
public string Gender { get; set; }

// JSON output:
// {
//   "User_Name": "Randy",
//   "User_Age": "42",
//   "Occupation": "Magician"
// }

API Overview

DSConverter (static)

DSNode

License

MIT License – free to use and modify.