NETool.Pack 0.5.2

NETool.Pack

介绍

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

软件架构

.Net8, .Net9, .Net10

安装教程

从 Nuget 安装最新版本。

Install-Package NETool.Pack

使用说明

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

快速入门

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

using System.NETool;

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

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

// <auto-generated by NETool.Generator 2025-08-09 11:42:06/>
// 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 NETool.Demo;

/// <summary>
/// NETool.Demo.Person 序列化扩展
/// </summary>
public partial class Person : 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 stringEncoding = StringEncoding.Utf8)
    {
        var writer = new ByteArray();
        #region 序列化
        writer.WriteInt32(this.Age);
        writer.WriteString(this.Name);
        #endregion 序列化
        return writer;
    }

    ///<inheritdoc/>
    public void Deserialize(scoped ReadOnlySpan<byte> span, Endian endian = Endian.Little, StringEncoding stringEncoding = StringEncoding.Utf8)
    {
        var reader = new ByteArray(span);
        #region 反序列化
        this.Age = reader.ReadInt32();
        this.Name = reader.ReadString();
        #endregion 反序列化
    }
}

/// <summary>
/// NETool.Demo.Person 深度拷贝的扩展方法
/// </summary>
public static class NETool_Demo_Person_DeepCopy_Extensions
{
    /// <summary>
    /// 获取已有 NETool.Demo.Person 对象的副本，需有默认的无参构造函数
    /// </summary>
    /// <param name="this">已有对象</param>
    /// <returns>NETool.Demo.Person 副本</returns>
    public static NETool.Demo.Person DeepCopy(this NETool.Demo.Person @this)
    {
        if (@this is null) return null;
        
        using var writer = @this.Serialize();
        var copy = new NETool.Demo.Person();
        copy.Deserialize(writer.Span);
        return copy;
    }

    /// <summary>
    /// 将已有 NETool.Demo.Person 对象深度拷贝到另一个 NETool.Demo.Person 对象
    /// </summary>
    /// <param name="this">已有 NETool.Demo.Person 对象</param>
    /// <param name="other">另一个 NETool.Demo.Person 对象</param>
    public static void DeepCopyTo(this NETool.Demo.Person @this, ref NETool.Demo.Person other)
    {
        if (@this is null) return;
        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] 特性的类;

• 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 特性的，序列化时将会忽略。

深度拷贝

标记为 [NEToolPackIgnore] 类源生成深度拷贝扩展方法

public static T DeepCopy(this T @this) // 类必须有无参数的构造方法
public static void DeepCopyTo(this T @this, ref T other)