TASON 1.1.2

包TASON

包含TASON序列化和反序列化的核心逻辑与内置类型实现。

反序列化模式

tason-net支持两种反序列化模式：自动类型模式和指定类型模式

指定类型模式

和其它序列化框架一致，通过指定所需的类型（泛型参数或者Type对象）来反序列化特定类型的实例。该模式下，

✅ 鸭子类型(Duck Type)反序列化

同一名称的TASON类型实例，可以有多种不同的.NET实现类型。

例如，定义一个TASON Color类型实例，可以将System.Windows.Media.Color，System.Drawing.Color，甚至UnityEngine.Color都作为Color类型实例进行反序列化。

✅ 多态(Polymorphism)反序列化

指定一个非泛型的抽象类或者接口T，允许多种不同的TASON对象实例映射到T，只要它们是T的子类型

• 支持IEnumerable<T>，可以将多种具体类的集合反序列化到其基类或者接口的集合

自定义集合类型

支持将IEnumerable<T>和IDictionary<TKey, TValue>反序列化为自定义的实现类型

• IEnumerable<T>的实现类需要有一个公共无参构造函数，或者有一个参数传入IEnumerable<T>的子类。
• IDictionary<TKey, TValue>的实现类需要有一个公共无参构造函数。

自动类型模式

TASON特色功能，通过TASON文本包含的信息自动匹配最合适的.NET类型进行反序列化。该模式下，

• 如果遇到TASON类型实例，会反序列化为该类型的默认.NET实现
• 对于嵌套数组或者对象，会自动反序列化为List<object>或者Dictionary<string, object>
• 可以使用dynamic变量来接收序列化的对象，从而无视复杂结构快速获取到所需的数据。相比之下，传统序列化框架只提供一些没有类型信息的语法节点，如System.Text.Json.JsonElement，遍历和处理此类节点，特别是反序列化深度嵌套的部分节点，以及使用现有.NET对象替换一部分节点十分困难。

自动类型模式尤其适合动态语言如JavaScript生成的复杂动态数据结构，在保留动态结构灵活性的同时，仍然保留强类型的部分。

例如在执行MongoDB查询时，可以避免前端因为序列化为JSON时，Date和Int64等类型变成字符串丢失类型，从而影响查询的执行结果的情况发生。

快速开始

using TASON;

// 使用默认序列化器
var serializer = TasonSerializer.Default;

// 使用默认实现注册POCO类
serializer.Registry.CreateObjectType(typeof(SomeModelClass));

// 序列化

var model = new SomeModelClass 
{
  SomeProperty = "SomeValue",
  LongValue = 2L << 56,
};
string tason = serializer.Serialize(model); 
// SomeModelClass({SomeProperty:"SomeValue",LongValue:Int64("144115188075855872")})


// 自动类型模式反序列化

var list = serializer.Deserialize($"[{tason}]"); 
// 得到List<object>，其中每个元素都是SomeModelClass

var dict = serializer.Deserialize("{a:1,b:'foo'}"); 
// 得到Dictionary<string, object>，其中每个键值对都是自动推断类型


// 指定类型模式反序列化

var list2 = serializer.Deserialize<ICollection<SomeModelClass>>($"[{tason}]"); 
//得到List<SomeModelClass>

.NET版本差异

⚠️ 由于不同.NET版本之间库API的差异，各个版本提供的功能存在区别，主要有以下方面：

基础数字类型

• CLR新增了一些数字类型
  • Half: 在不支持的环境中使用了Half包， 在支持的.NET版本中，使用原生的System.Half，两者公开的API几乎一致。
  • Int128和NFloat: 仅在受支持的版本中启用
• .NET 7引入的泛型数学，特别是abstract static接口方法的支持，对基础数据类型的支持有较大的变动，例如泛型参数约束等
• 字符串解析的支持不同，特别是非十进制解析，部分未提供的方法采用了可能效率较低的实现

日期类型

• .NET 6新增了一些日期类型DateOnly和TimeOnly：在不受支持的环境中使用了Portable.System.DateTimeOnly包，在支持的版本中使用原生类型，两者公开的API几乎一致。

类型支持

以下列出了序列化和反序列化中.NET类型的支持情况，不含TASON规范禁止的类型

完全支持的类型

• 所有基元类型和数字类型，包含BigInteger等
• 所有带有无参构造函数的非泛型、非抽象类
• 注册了自定义TASON类型信息的标量类型和对象类型，包括所有内置类型
• 以上类型作为嵌套类型
• 以上类型的数组
• Nullable<T>类型

完全支持序列化，但反序列化有一定限制的类型

• 完全支持的类型作为泛型参数T的集合类型
  • IEnumerable<T>、IDictionary<string, TValue>及其衍生接口
  • 具有无参构造函数，或者IEnumerable<T>类型参数构造函数的IEnumerable<T>非抽象实现类，如List<T>
  • 具有无参构造函数的IDictionary<string, TValue>的非抽象实现类，如Dictionary<string, TValue>
• 非泛型集合类
  • 仅支持ArrayList、Queue、Stack
• Key不是字符串的IDictionary<TKey, TValue>类型，需要开启参数
• 抽象类和IEnumerable<T>以外的接口
  • 仅支持对象类型实例，可以进行多态反序列化
• 基元类型以外的结构（值类型）
  • 由于值类型的反射限制，除基元类型以外，必须注册类型实例才可以反序列化

可以序列化，暂时无法反序列化的类型

• ValueTuple
• 泛型类
• 匿名类型

内置类型支持

相比JavaScript版本，针对语言特性提供了更多的内置类型支持

整数和浮点数类型

标✅是TASON默认支持类型，标✨是.NET特有类型

⚠️ TASON将IntPtr和UIntPtr视为本机大小的整数，即C#关键字nint和nuint对应的CLR类型，而不是指针的包装类型。 在序列化时会使用对应的普通整数类型进行序列化，因此可以避免一些可能的安全问题。 但为了避免在代码中无意识地转成指针类型，仍然需要开启AllowUnsafeTypes选项。