C#的MessagePack（unity）--02

高级API (MessagePackSerializer)

MessagePackSerializer类是MessagePack for C# 的入口点。静态方法构成了MessagePack for C# 的主要API。

API	Description
`Serialize<T>`	将一个对象图序列化为MessagePack二进制块。可以使用异步变体获取Stream。也有非泛型重载可用。
`Deserialize<T>`	将MessagePack二进制转换为对象图。可用于Stream的异步变体。也有非泛型重载可用。
`SerializeToJson`	将MessagePack兼容的对象图序列化为JSON，而不是MessagePack。这对调试很有帮助。
`ConvertToJson`	将MessagePack二进制转换为JSON。这对调试很有帮助
`ConvertFromJson`	将JSON转换为MessagePack二进制。

MessagePack for C#基本上使用IBufferWriter <byte>进行序列化，并使用ReadOnlySequence <byte> 或Memory <byte>进行反序列化。提供了方便的方法重载来方便地与常见的缓冲区类型和.NET Stream 类配合使用，但这些便捷重载需要复制缓冲区一次，因此有一定的开销。

高级API内部使用内存池来避免不必要的内存分配。如果结果大小小于64K，则只为返回字节分配GC内存。

每个serialize / deserialize方法都可选地接受一个MessagePackSerializerOptions参数，可用于指定要使用的自定义IFormatterResolver或激活LZ4压缩支持。

单个Stream上的多个MessagePack结构

要反序列化包含多个连续MessagePack数据结构的流，您可以使用MessagePackStreamReader类来高效地识别每个数据结构的ReadOnlySequence <byte> 并对其进行反序列化。例如：

static async Task<List<T>> DeserializeListFromStreamAsync<T>(Stream stream, CancellationToken cancellationToken)
{
    var dataStructures = new List<T>();
    using (var streamReader = new MessagePackStreamReader(stream))
    {
        while (await streamReader.ReadAsync(cancellationToken) is ReadOnlySequence<byte> msgpack)
        {
            dataStructures.Add(MessagePackSerializer.Deserialize<T>(msgpack, cancellationToken: cancellationToken));
        }
    }

    return dataStructures;
}

低级API (IMessagePackFormatter<T>)

IMessagePackFormatter<T> 接口负责序列化一个唯一的类型。例如，Int32Formatter : IMessagePackFormatter<Int32>表示Int32 MessagePack 序列化器

public interface IMessagePackFormatter<T>
{
    void Serialize(ref MessagePackWriter writer, T value, MessagePackSerializerOptions options);
    T Deserialize(ref MessagePackReader reader, MessagePackSerializerOptions options);
}

有许多内置格式器位于MessagePack.Formatters下。你的自定义类型通常会自动得到支持，并使用动态代码生成来生成新IMessagePackFormatter<T>类型的内置类型解析器。对于不支持此功能的平台，请参阅我们的AOT代码生成支持。

然而，一些类型（特别是由第三方库或运行时本身提供的类型）无法适当地注解，无合同序列化会产生效率低下甚至错误的结果。为了更好地控制此类自定义类型的序列化，编写您自己的IMessagePackFormatter<T>实现。下面是一个这样的自定义格式器实现的例子。请注意它使用的原始API，该API在下一节中描述。

/// <summary>Serializes a <see cref="FileInfo" /> by its full path as a string.</summary>
public class FileInfoFormatter : IMessagePackFormatter<FileInfo>
{
    public void Serialize(
      ref MessagePackWriter writer, FileInfo value, MessagePackSerializerOptions options)
    {
        if (value == null)
        {
            writer.WriteNil();
            return;
        }

        writer.WriteString(value.FullName);
    }

    public FileInfo Deserialize(
      ref MessagePackReader reader, MessagePackSerializerOptions options)
    {
        if (reader.TryReadNil())
        {
            return null;
        }

        options.Security.DepthStep(ref reader);

        var path = reader.ReadString();

        reader.Depth--;
        return new FileInfo(path);
    }
}

DepthStep 和 Depth--语句提供了一层安全保护，在反序列化不受信任的数据时，可能会导致拒绝服务攻击，发送会导致堆栈溢出异常的消息包数据，并崩溃进程。这两个语句应该包围任何IMessagePackFormatter<T>.Deserialize 方法的主要部分。

注意：一个message pack 格式器必须读写一个数据结构。在上述例子中我们只是读取或写入一个字符串。如果你有多个元素要写入，必须在前面加上map或array头。在反序列化时必须读取整个map/array。例如：

public class MySpecialObjectFormatter : IMessagePackFormatter<MySpecialObject>
{
    public void Serialize(
      ref MessagePackWriter writer, MySpecialObject value, MessagePackSerializerOptions options)
    {
        if (value == null)
        {
            writer.WriteNil();
            return;
        }

        writer.WriteArrayHeader(2);
        writer.WriteString(value.FullName);
        writer.WriteString(value.Age);
    }

    public MySpecialObject Deserialize(
      ref MessagePackReader reader, MessagePackSerializerOptions options)
    {
        if (reader.TryReadNil())
        {
            return null;
        }

        options.Security.DepthStep(ref reader);

        string fullName = null;
        int age = 0;

        // Loop over *all* array elements independently of how many we expect,
        // since if we're serializing an older/newer version of this object it might
        // vary in number of elements that were serialized, but the contract of the formatter
        // is that exactly one data structure must be read, regardless.
        // Alternatively, we could check that the size of the array/map is what we expect
        // and throw if it is not.
        int count = reader.ReadArrayHeader();
        for (int i = 0; i < count; i++)
        {
            switch (i)
            {
                case 0:
                    fullName = reader.ReadString();
                    break;
                case 1:
                    age = reader.ReadInt32();
                    break;
                default:
                    reader.Skip();
                    break;
            }
        }

        reader.Depth--;
        return new MySpecialObject(fullName, age);
    }
}

unity 支持

Unity最低支持版本为2018.3，API 兼容级别同时支持.NET 4.x 和.NET Standard 2.0。

可以从Release 页面安装unitypackage。如果构建目标是.NET Framework 4.x 并在mono上运行，可以直接使用它。但如果构建目标是IL2CPP，则不能使用Dynamic***Resolver，因此需要使用预代码生成。请参阅预代码生成部分。

MessagePack for C# 包含一些NuGet中原先提供的额外System.*.dll库。它们位于Plugins文件夹下。如果其他包使用这些库（例如使用System.Runtime.CompilerServices.Unsafe.dll的Unity Collections包），为了避免冲突，请删除Plugins下的DLL。

目前CompositeResolver.Create在IL2Cpp上不起作用，因此建议使用StaticCompositeResolver.Instance.Register。

在Unity中，MessagePackSerializer可以使用内置扩展UnityResolver将Vector2、Vector3、Vector4、Quaternion、Color、Bounds、Rect、AnimationCurve、Keyframe、Matrix4x4、Gradient、Color32、RectOffset、LayerMask、Vector2Int、Vector3Int、RangeInt、RectInt、BoundsInt及其可空、数组和列表类型序列化。它默认包含在StandardResolver中。

MessagePack for C# 还有一个额外的不安全扩展。UnsafeBlitResolver 是一个特殊解析器，用于结构数组的极高但不安全的序列化/反序列化