BugFree.Serialization 1.2.2026.613-beta1514

BugFree.Serialization

基于 .NET 的多格式文本序列化库，提供统一接口支持 JSON、XML、YAML、INI、TOML、Toon 六种格式的序列化与反序列化。

功能特性

• 多格式支持 — 通过统一的 ITextSerializer 接口切换 JSON、XML、YAML、INI、TOML、Toon 格式
• 扩展方法 — 提供 .ToJson()、.FromJson()、.ToXml()、.FromXml()、.ToYaml()、.FromYaml()、.ToIni()、.FromIni()、.ToToml()、.FromToml() 等便捷扩展
• JSON 字节序列化 — 支持 UTF-8 JSON 字节数组的序列化与反序列化
• 智能默认值 — 空文本输入自动返回目标类型的默认实例（空字符串、空数组等）
• JSON 增强转换器 — 内置对 IPAddress、IPEndPoint、Int64（大数精度保护）、可空值类型空白字符串还原的支持
• 跨平台 — 支持 .NET 8.0 和 .NET 10.0

支持的格式

安装

NuGet

dotnet add package BugFree.Serialization

依赖

• YamlDotNet (>= 18.0.0) — YAML 序列化
• Tomlyn (>= 2.4.1) — TOML 序列化
• ToonNet.Core (>= 1.4.0) — Toon 序列化

快速开始

1. 通过 SerializationType 获取序列化器

using BugFree.Serialization;

// 通过枚举获取指定格式的序列化器
var jsonSerializer = SerializationType.Json.GetTextSerializer();
var xmlSerializer = SerializationType.Xml.GetTextSerializer();
var yamlSerializer = SerializationType.Yaml.GetTextSerializer();
var iniSerializer = SerializationType.Ini.GetTextSerializer();
var tomlSerializer = SerializationType.Toml.GetTextSerializer();

2. JSON 序列化与反序列化

using BugFree.Serialization;

var model = new MyModel { Name = "BugFree", Version = 1 };

// 序列化为 JSON 文本
var json = model.ToJson();
// 输出: {
//   "name": "BugFree",
//   "version": 1
// }

// 从 JSON 文本反序列化
var restored = json.FromJson<MyModel>();

// 序列化为 UTF-8 字节数组
var bytes = model.ToJsonBytes();

// 从字节数组反序列化
var restoredFromBytes = bytes.FromJsonBytes<MyModel>();

3. XML / YAML / INI / TOML 序列化

// XML
var xml = model.ToXml();
var fromXml = xml.FromXml<MyModel>();

// YAML
var yaml = model.ToYaml();
var fromYaml = yaml.FromYaml<MyModel>();

// INI（仅支持原始类型属性）
var ini = model.ToIni();
var fromIni = ini.FromIni<MyModel>();

// TOML
var toml = model.ToToml();
var fromToml = toml.FromToml<MyModel>();

4. 自定义 JSON 序列化选项

using System.Text.Json;

var options = new JsonSerializerOptions
{
    WriteIndented = false,
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
};

var json = model.ToJson(options);
var restored = json.FromJson<MyModel>(options);

// 也支持字节数组
var bytes = model.ToJsonBytes(options);
restored = bytes.FromJsonBytes<MyModel>(options);

5. 空输入安全处理

所有序列化器在遇到空文本或空白文本时，会自动返回目标类型的默认实例：

// 字符串类型返回空字符串
var str = "".FromJson<string>();           // ""

// 数组类型返回空数组
var arr = "".FromJson<int[]>();            // []

// 有公共无参构造的类型返回新实例
var model = "".FromXml<MyModel>();         // new MyModel()

// 无公共无参构造的类型返回 null

JSON 增强转换器

JsonTextSerializer 内置了以下自定义转换器：

序列化格式限制

JSON

• 接口/抽象类型需要自定义转换器或多态配置
• 默认不处理循环引用
• 只序列化可读写的公共属性

XML

• Dictionary 不被直接支持
• 接口/抽象类型属性不能反序列化
• 要求公共无参构造
• 不支持循环引用

YAML

• 默认不保留注释
• 接口/抽象类型需自定义转换器
• 命名约定默认与模型一致

INI

• 不支持 List / Array / Dictionary / 自定义对象的嵌套
• 只写出可读属性，读取时仅处理有 setter 的属性

目标框架

• .NET 8.0
• .NET 10.0

项目结构

BugFree.Serialization/
├── BugFree.Serialization.slnx          # 解决方案文件
├── BugFree.Serialization/              # 主类库
│   ├── IByteSerializer.cs              # 字节序列化器接口（内部）
│   ├── ITextSerializer.cs              # 文本序列化器统一接口
│   ├── SerializationType.cs            # 序列化格式枚举
│   ├── SerializationExtensions.cs      # 序列化器选择与默认实例创建
│   ├── Json/                           # JSON 序列化实现
│   │   └── Converters/                 # 自定义 JSON 转换器
│   ├── Xml/                            # XML 序列化实现
│   ├── Yaml/                           # YAML 序列化实现
│   ├── Ini/                            # INI 序列化实现
│   ├── Toml/                           # TOML 序列化实现
│   └── Toon/                           # Toon 序列化实现
└── BugFree.Serialization.TestProject/  # 单元测试项目

许可证

本项目基于 MIT 许可证开源。)