Edision_li

C#的MessagePack（unity）--01

简介

c#中极快的MessagePack序列化器。它比MsgPack-Cli快10倍，并且优于其他c#序列化器。

c#的MessagePack还内置了对LZ4压缩的支持——一种非常快的压缩算法。性能非常重要，特别是在游戏、分布式计算、微服务或数据缓存等应用程序中。

MessagePack具有紧凑的二进制大小和一套完整的通用表达数据类型。

地址：GitHub - MessagePack-CSharp/MessagePack-CSharp: Extremely Fast MessagePack Serializer for C#(.NET, .NET Core, Unity, Xamarin). / msgpack.org[C#]

安装

查看地址中README.md,分别有NuGet packages和UnityPack。对于Unity项目，发布页面提供了可下载的.unitypackage文件。当在Unity IL2CPP或Xamarin AOT环境中使用时，请仔细阅读预代码生成部分。

configuration中APILevel改为：.Net Framework

开始

定义要序列化的结构或类，并用[MessagePackObject]属性对其进行注释。用[Key]属性注释值应该序列化的成员(字段和属性)。

using MessagePack;
using UnityEngine;

public class Test_MessagePack : MonoBehaviour
{

}

[MessagePackObject]
public class MyClass
{
    // Key attributes take a serialization index (or string name)
    /*键属性接受序列化索引(或字符串名称)*/
    // The values must be unique and versioning has to be considered as well.
    /*这些值必须是唯一的，并且必须考虑版本控制。*/
    [Key(0)]
    public int Age { get; set; }

    [Key(1)]
    public string FirstName { get; set; }

    [Key(2)]
    public string LastName { get; set; }

    // 所有不应该序列化的字段或属性必须用[IgnoreMember]注释。
    [IgnoreMember]
    public string FullName { get { return FirstName + LastName; } }
}

调用 MessagePackSerializer.Serialize/Deserialize 来序列化/反序列化您的对象实例。您可以使用 ConvertToJson 方法获取任何 MessagePack 二进制数据的可读表示形式。

分析器

MessagePackAnalyzer 包有助于：

1. 自动为可序列化对象定义。
2. 在不正确使用属性、成员可访问性等时生成编译器警告。

内置支持的类型以及自定义自行看官方。

对象序列化

MessagePack for C# 可以序列化您自己的公共类或结构类型。默认情况下，可序列化类型必须使用 [MessagePackObject] 特性进行注释，成员使用 [Key] 特性进行注释。键可以是索引（int）或任意字符串。如果所有键都是索引，则会使用数组进行序列化，这在性能和二进制大小方面具有优势。否则，将使用 MessagePack 映射（字典）。如果您使用 [MessagePackObject(keyAsPropertyName: true)] ，则成员不需要显式的 Key 特性，但是会使用字符串键。

[MessagePackObject]
public class Sample1
{
    [Key(0)]
    public int Foo { get; set; }
    [Key(1)]
    public int Bar { get; set; }
}

[MessagePackObject]
public class Sample2
{
    [Key("foo")]
    public int Foo { get; set; }
    [Key("bar")]
    public int Bar { get; set; }
}

[MessagePackObject(keyAsPropertyName: true)]
public class Sample3
{
    //不需要 Key 特性。
    public int Foo { get; set; }

    //如果要忽略公共成员，可以使用 IgnoreMember 特性。
    [IgnoreMember]
    public int Bar { get; set; }
}
    private void Test_02()
    {
        // [10,20]
        Debug.Log(MessagePackSerializer.SerializeToJson(new Sample1 { Foo = 10, Bar = 20 }));

        // {"foo":10,"bar":20}
        Debug.Log(MessagePackSerializer.SerializeToJson(new Sample2 { Foo = 10, Bar = 20 }));

        // {"Foo":10}
        Debug.Log(MessagePackSerializer.SerializeToJson(new Sample3 { Foo = 10, Bar = 20 }));
    }

所有公共实例成员（包括字段和属性）都将被序列化。如果要忽略某些公共成员，请使用 [IgnoreMember] 特性注解该成员。
请注意，任何可序列化的结构或类都必须具有公共访问权限；私有和内部结构和类不能被序列化！要求 MessagePackObject 注释的默认设置是为了强制显式性，因此可能有助于编写更健壮的代码。
您应该使用索引（int）键还是字符串键？我们建议使用索引键以实现更快的序列化和比字符串键更紧凑的二进制表示形式。然而，字符串键中的字符串中的附加信息在调试时非常有用。
当类发生变化或被扩展时，要注意版本控制。MessagePackSerializer 将初始化成员为它们的默认值，如果序列化二进制数据中不存在某个键，则意味着使用引用类型的成员可以初始化为 null。如果您使用索引（int）键，则键应从 0 开始，并且应该是连续的。如果后续版本停止使用某些成员，则应在其他客户端有机会更新并删除对这些成员的使用之前保留这些废弃成员（C# 提供了一个 Obsolete 属性来注解此类成员）。此外，当索引键的值“跳动”很多时，会在序列中留下间隙，这将对二进制大小产生负面影响，因为 null 占位符会被插入到生成的数组中。但是，为了避免客户端之间的兼容性问题或尝试反序列化遗留数据包时出现兼容性问题，不应重用已删除成员的索引。

索引间隙和占位符的例子:

[MessagePackObject]
public class IntKeySample
{
    [Key(3)]
    public int A { get; set; }
    [Key(10)]
    public int B { get; set; }
}
   
 private void Test_03()
{
   // [null,null,null,0,null,null,null,null,null,null,0]
   Debug.Log(MessagePackSerializer.SerializeToJson(new IntKeySample()));
}

如果您不希望使用 MessagePackObject/Key 特性进行显式注解，而是希望像 e.g. Json.NET 一样使用 MessagePack for C#，则可以使用无合同解析器。

    private void Test_04()
    {
        var data = new ContractlessSample { MyProperty1 = 99, MyProperty2 = 9999 };
        var bin = MessagePackSerializer.Serialize(
          data,
          MessagePack.Resolvers.ContractlessStandardResolver.Options);

        // {"MyProperty1":99,"MyProperty2":9999}
        Debug.Log(MessagePackSerializer.ConvertToJson(bin));

        // 你也可以将ContractlessStandardResolver设置为默认值。
        // (全局状态;不建议在编写库代码时使用)
        MessagePackSerializer.DefaultOptions = MessagePack.Resolvers.ContractlessStandardResolver.Options;

        // Now serializable...
        var bin2 = MessagePackSerializer.Serialize(data);
        // {"MyProperty1":99,"MyProperty2":9999}
        Debug.Log(MessagePackSerializer.ConvertToJson(bin2));
    }
public class ContractlessSample
{
    public int MyProperty1 { get; set; }
    public int MyProperty2 { get; set; }
}

如果您希望序列化私有成员，您可以使用 *AllowPrivate 解析器之一。

如果您希望使用 MessagePack for C# 类似于 BinaryFormatter，具有无类型的序列化 API，则可以使用无类型解析器和助手。请参阅“无类型”部分。解析器是为 MessagePack for C# 添加自定义类型专用支持的方法。请参考“扩展点”部分。

DataContract compatibility

您可以使用 [DataContract] 标记代替 [MessagePackObject] 标记。如果类型带有 DataContract 标记，您可以使用 [DataMember] 标记代替 [Key] 标记以及 [IgnoreDataMember] 替换 [IgnoreMember] 标记。

然后 [DataMember(Order = int)] 行为与 [Key(int)] 相同，[DataMember(Name = string)] 与 [Key(string)] 相同，而 [DataMember] 则与 [Key(nameof(成员名))] 相同。

使用 DataContract（例如在共享库中）可以使您的类/结构独立于 MessagePack for C# 序列化。但是，它不被分析器支持，也不被 mpc 工具用于代码生成。此外，诸如 UnionAttribute、MessagePackFormatter、SerializationConstructor 等功能也无法使用。因此，我们建议尽可能使用特定的 MessagePack for C# 注释。

MessagePack for C# 支持只读/不可变（ readonly/immutable）对象成员的序列化。

MessagePack for C# 支持只读/不可变对象/成员的序列化。例如，这个结构体可以被序列化和反序列化。

[MessagePackObject]
public struct Point
{
    [Key(0)]
    public readonly int X;
    [Key(1)]
    public readonly int Y;

    public Point(int x, int y)
    {
        this.X = x;
        this.Y = y;
    }
}
    private void Test_06()
    {
        var data = new Point(99, 9999);
        var bin = MessagePackSerializer.Serialize(data);
        //[99,9999]
        Debug.Log(MessagePackSerializer.ConvertToJson(bin));
        // 反序列化不可变对象
        var point = MessagePackSerializer.Deserialize(bin);
        //99**9999
        Debug.Log($"{point.X}**{point.Y}");
    }

MessagePackSerializer 将选择与索引键匹配的参数列表最好的构造函数，或者使用参数名称作为字符串键。如果找不到合适的构造函数，则会抛出 MessagePackDynamicObjectResolverException：无法找到匹配的构造函数参数异常。可以使用 [SerializationConstructor] 注解手动指定要使用的构造函数。

[MessagePackObject]
public struct Point
{
    [Key(0)]
    public readonly int X;
    [Key(1)]
    public readonly int Y;

    [SerializationConstructor]
    public Point(int x)
    {
        this.X = x;
        this.Y = -1;
    }

    // 如果没有标记属性，则使用这个（最匹配的参数）。
    public Point(int x, int y)
    {
        this.X = x;
        this.Y = y;
    }
}

序列化回调

在序列化/反序列化过程中，实现了 IMessagePackSerializationCallbackReceiver 接口的对象将收到 OnBeforeSerialize 和 OnAfterDeserialize 调用。

[MessagePackObject]
public class SampleCallback : IMessagePackSerializationCallbackReceiver
{
    [Key(0)]
    public int Key { get; set; }

    public void OnBeforeSerialize()
    {
        Debug.Log("OnBefore");
    }

    public void OnAfterDeserialize()
    {
        Debug.Log("OnAfter");
    }
}

联合

MessagePack for C# 支持接口类型和抽象类类型的对象的序列化。它的行为类似于 XmlInclude 或 ProtoInclude。在 MessagePack for C# 中，这些称为联合。只有接口和抽象类才允许标注联合属性。需要唯一的联合密钥。

// 注释继承类型
[MessagePack.Union(0, typeof(FooClass))]
[MessagePack.Union(1, typeof(BarClass))]
public interface IUnionSample { }

[MessagePackObject]
public class FooClass : IUnionSample
{
    [Key(0)]
    public int XYZ { get; set; }
}

[MessagePackObject]
public class BarClass : IUnionSample
{
    [Key(0)]
    public string OPQ { get; set; }
}
    private void Test_08()
    {
        //IUnionSample data = new FooClass() { XYZ = 999 };
        IUnionSample data = new BarClass() { OPQ = "BarClass" };
        // 序列化接口类型的对象。
        var bin = MessagePackSerializer.Serialize(data);

        // 再次进行反序列化。
        var reData = MessagePackSerializer.Deserialize(bin);

        // 与c# 7.0中的类型切换一起使用
        switch (reData)
        {
            case FooClass x:
                Debug.Log(x.XYZ);
                break;
            case BarClass x:
                Debug.Log(x.OPQ);
                break;
            default:
                break;
        }
    }

请注意，在衍生类型中不能重复使用在父类型中已经存在的相同键，因为内部会使用单一的扁平数组或映射，并且因此不能有重复的索引/键。

动态（无类型）反序列化

当调用MessagePackSerializer.Deserialize