NETool.Pack 0.7.0

NETool.Pack

介绍

NETool.Pack 是 NETool 的适用于 C# 的零编码二进制序列化程序。
参考 MemoryPack，支持的类型不及其丰富，但足以满足大部分需求。
NETool.Pack 速度之所以如此之快，是由于其特定于 C# 优化的二进制格式，利用 .NET 8+ 和 C# 13 以及增量源生成器（.NET Standard 2.0），另外包括 Span, ReadOnlySpan 以及内存池 ArrayPool 的使用。

软件架构

.Net8, .Net9, .Net10

安装教程

从 Nuget 安装最新版本。

Install-Package NETool.Pack

快速入门

定义要序列化的结构或类，并使用属性和关键字对其进行注释。[NEToolPackable] partial

using System.NETool;

[NEToolPackable]
public partial class Person
{
    public int Age { get; set; }
    public string Name { get; set; }
}

源生成的代码实现了 INEToolPackMembers、INEToolPackable 接口，包含四个函数:

/// <summary>
/// NETool 序列化接口
/// </summary>
public interface INEToolPackable
{
    /// <summary>
    /// 排除数据字段
    /// </summary>
    string ExcludedMembers();

    /// <summary>
    /// 未知数据字段
    /// </summary>
    string UnknownMembers();

    /// <summary>
    /// NETool 序列化方法
    /// </summary>
    /// <param name="endian">字节序: Little 为小端字节(低字节序)，Big 为大端字节序(高字节序)</param>
    /// <param name="encoding">字符编码</param>
    /// <param name="zipType">压缩及加密算法类型</param>
    /// <param name="password">密码</param>
    /// <returns>字节数组对象</returns>
    ByteArray Serialize(Endian endian = Endian.Little, StringEncoding encoding = StringEncoding.UTF8, ZipType zipType = ZipType.None, string password = null);

    /// <summary>
    /// NETool 反序列化方法
    /// </summary>
    /// <param name="span">数据</param>
    /// <param name="endian">字节序: Little 为小端字节(低字节序)，Big 为大端字节序(高字节序)</param>
    /// <param name="encoding">字符编码</param>
    /// <param name="zipType">压缩及加密算法类型</param>
    /// <param name="password">密码</param>
    void Deserialize(scoped ReadOnlySpan<byte> span, Endian endian = Endian.Little, StringEncoding encoding = StringEncoding.UTF8, ZipType zipType = ZipType.None, string password = null);
}

另外还实现了两个深度拷贝函数:

/// <summary>
/// 获取已有 Sunny.Serialization.Demo.Person 对象的副本，需有默认的无参构造函数
/// </summary>
/// <returns>Sunny.Serialization.Demo.Person 副本</returns>
public Sunny.Serialization.Demo.Person DeepCopy()

    /// <summary>
/// 将已有 Sunny.Serialization.Demo.Person 对象深度拷贝到另一个不为空的 Sunny.Serialization.Demo.Person 对象
/// </summary>
/// <param name="other">另一个 Sunny.Serialization.Demo.Person 对象</param>
public void DeepCopyTo(Sunny.Serialization.Demo.Person other)

序列化代码由实现接口的 C# 源生成器功能生成。在 Visual Studio 中，可以使用类名称上的快捷方式 F12 检查生成的代码，然后选择 *.Person.Properties.g.cs

// <auto-generated by NETool.Generator 2025-08-14 13:42:57/>
// ReSharper disable once InconsistentNaming

using System;
using System.Buffers;
using System.Collections.Concurrent;
using System.Collections.Generic;
using System.Drawing;
using System.Globalization;
using System.NETool;
using System.Runtime.CompilerServices;
using System.Text;

namespace Sunny.Serialization.Demo;

/// <summary>
/// Sunny.Serialization.Demo.Person 序列化扩展
/// </summary>
public partial class Person : INEToolPackMembers, INEToolPackable
{
    /// <summary>
    /// 排除的成员 0 个
    /// </summary>
    public string ExcludedMembers()
    {
        return string.Empty;
    }

    /// <summary>
    /// 未知的成员 0 个
    /// </summary>
    public string UnknownMembers()
    {
        return string.Empty;
    }

    ///<inheritdoc/>
    public ByteArray Serialize(Endian endian = Endian.Little, StringEncoding encoding = StringEncoding.UTF8, ZipType zipType = ZipType.None, string password = null)
    {
        var writer = new ByteArray(endian, encoding);
        #region 序列化
        writer.WriteInt32(this.Age);
        writer.WriteString(this.Name);
        #endregion 序列化
        var result = zipType.Compress(writer.Span, password);
        writer.Dispose();
        return result;
    }

    ///<inheritdoc/>
    public void Deserialize(scoped ReadOnlySpan<byte> span, Endian endian = Endian.Little, StringEncoding encoding = StringEncoding.UTF8, ZipType zipType = ZipType.None, string password = null)
    {
        var unZipped = zipType.Decompress(span, password);
        var reader = new ByteArray(unZipped.Span, endian, encoding);
        #region 反序列化
        this.Age = reader.ReadInt32();
        this.Name = reader.ReadString();
        #endregion 反序列化
        unZipped.Dispose();
    }

    /// <summary>
    /// 获取已有 Sunny.Serialization.Demo.Person 对象的副本，需有默认的无参构造函数
    /// </summary>
    /// <returns>Sunny.Serialization.Demo.Person 副本</returns>
    public Sunny.Serialization.Demo.Person DeepCopy()
    {
        using var writer = this.Serialize();
        var copy = new Sunny.Serialization.Demo.Person();
        copy.Deserialize(writer.Span);
        return copy;
    }

    /// <summary>
    /// 将已有 Sunny.Serialization.Demo.Person 对象深度拷贝到另一个不为空的 Sunny.Serialization.Demo.Person 对象
    /// </summary>
    /// <param name="other">另一个 Sunny.Serialization.Demo.Person 对象</param>
    public void DeepCopyTo(Sunny.Serialization.Demo.Person other)
    {
        if (other is null) return;
        
        using var writer = this.Serialize();
        other.Deserialize(writer.Span);
    }

}

调用序列化/反序列化对象实例:

 var person = new Person
 {
     Age = 30,
     Name = "Sunny"
 };

 // 序列化
 var byteArray = person.Serialize();
 Console.WriteLine($"Serialized Person: {byteArray.Span.ToHexString()}");

 // 反序列化
 person.Deserialize(byteArray.Span);
 Console.WriteLine($"Deserialized Person: Age={person.Age}, Name={person.Name}");
 byteArray.Dispose();

 // 深拷贝
 Person other = person.DeepCopy();
 Console.WriteLine($"Deep Copied Person: Age={other.Age}, Name={other.Name}");

输出结果:

Serialized Person: 1E0000000553756E6E79
Deserialized Person: Age=30, Name=Sunny
Deep Copied Person: Age=30, Name=Sunny

内置支持的类型

• 1 基础类型: bool, byte, sbyte, char, short, ushort, int, uint, long, ulong, float, double, decimal, Half, string;

• 2 扩展类型: 原生的 DateTime, Point, PointF, Size, SizeF, Color, Rectangle, RectangleF, TimeSpan, Guid, Version, Uri, TimeZoneInfo, CultureInfo 类型，System.NETool 扩展的 IpV4, IpV4Point, GuidV7, LngLat, SystemTime, MiniSystemTime 类型;

• 3 枚举类型: enum;

• 4 结构类型: struct, 标记为 [InlineArray(n)] 特性的结构体;

• 5 结构类型: struct, 标记为 [StructLayout(LayoutKind.Explicit, Pack = 1)] 特性的结构体;

• 6 可序列化类: class, 标记为 [NEToolPackable] 特性的类，类必须增加 partial 关键字，并有无参数的构造函数;

• 7 一维数组: T[], 其中 T 是上述 1、2、3、4、5 、6类型之一;

• 8 列表：List<T>, ConcurrentList<T>, 其中 T 是上述 1、2、3、4、5 、6类型之一;

• 9 字典：Dictionary<TKey, TValue>, ConcurrentDictionary<TKey, TValue>, 其中 TKey 和 TValue 是上述 1、2、3、4、5、6 类型之一;

类只有1 基础类型时，序列化与原生的 System.IO.BinaryWriter 完全一致

定义 [NEToolPackable] class

[NEToolPackable] 特性注释 class 类，定义为 public 或者 internal，类必须增加 partial 关键字，并有无参数的构造函数。类不能为继承的子类。

类序列化的字段包含：

• 字段 (filed) ，必须标记为 public，
• 属性 (Property)，必须标记为 public，并且有公开的 get；set；

标记为 [NEToolPackIgnore] 或者 [IgnoreDataMember] 或者带有其他 Ignore 特性的，序列化时将会忽略。