终极MessagePack-CSharp版本迁移指南：从v1.x到最新版本的平滑升级完整教程

终极MessagePack-CSharp版本迁移指南：从v1.x到最新版本的平滑升级完整教程

【免费下载链接】MessagePack-CSharpExtremely Fast MessagePack Serializer for C#(.NET, .NET Core, Unity, Xamarin). / msgpack.org[C#]项目地址: https://gitcode.com/gh_mirrors/me/MessagePack-CSharp

MessagePack-CSharp是一个超快速的MessagePack序列化器，适用于C#（.NET、.NET Core、Unity、Xamarin）。本指南将帮助您从v1.x版本平滑升级到最新版本，涵盖主要API变更、行为差异和迁移步骤，确保您的项目顺利过渡到新版本。

为什么需要升级MessagePack-CSharp？

MessagePack-CSharp的新版本带来了显著的性能提升、API改进和新功能支持。从v1.x到v3.x的升级不仅优化了序列化/反序列化效率，还引入了更灵活的配置选项和更好的跨平台兼容性。特别是v3版本默认启用了AOT源代码生成，大幅提升了运行时性能，同时通过Roslyn源生成器提供了更强大的类型处理能力。

版本演进概览

• v1.x：基础功能实现，支持核心序列化/反序列化
• v2.x：引入MessagePackSerializerOptions，重构API，提升性能
• v3.x：默认启用AOT源生成，改进分析器，增强Unity支持

准备工作：升级前的必要检查

在开始升级前，请确保：

1. 备份项目：确保您有项目的最新备份，以防升级过程中出现问题
2. 检查依赖项：确认项目中所有依赖MessagePack-CSharp的库都可以兼容新版本
3. 更新开发环境：对于v3版本，需要.NET SDK 6.0或更高版本，Unity用户需要2022.3.12f1或更高版本

从v1.x迁移到v2.x的核心步骤

1. 更新包引用

将项目中的MessagePack-CSharp包引用从1.x版本更新到2.x版本：

<PackageReference Include="MessagePack" Version="2.x.x" />

2. 适应MessagePackSerializerOptions

v2.x引入了MessagePackSerializerOptions类，替代了之前直接使用IFormatterResolver的方式。这一变化使配置更加灵活和类型安全。

旧代码（v1.x）：

var msgpack = MessagePackSerializer.Serialize(objectGraph, StandardResolverAllowPrivate.Instance); var deserializedGraph = MessagePackSerializer.Deserialize<MyType>(msgpack, StandardResolverAllowPrivate.Instance);

新代码（v2.x）：

var options = StandardResolverAllowPrivate.Options; var msgpack = MessagePackSerializer.Serialize(objectGraph, options); var deserializedGraph = MessagePackSerializer.Deserialize<MyType>(msgpack, options);

3. 处理压缩配置变更

v2.x中移除了LZ4MessagePackSerializer类，压缩功能通过MessagePackSerializerOptions配置：

旧代码（v1.x）：

byte[] buffer = LZ4MessagePackSerializer.Serialize("hi");

新代码（v2.x）：

static readonly var lz4Options = MessagePackSerializerOptions.Standard .WithCompression(MessagePackCompression.Lz4BlockArray); byte[] buffer = MessagePackSerializer.Serialize("hi", lz4Options);

4. 调整自定义格式化器

v2.x对IMessagePackFormatter<T>接口进行了重大调整，使用MessagePackWriter和MessagePackReader替代了原始字节数组操作：

旧代码（v1.x）：

public int Serialize(ref byte[] bytes, int offset, Int16? value, IFormatterResolver formatterResolver) { if (value == null) { return MessagePackBinary.WriteNil(ref bytes, offset); } else { return MessagePackBinary.WriteInt16(ref bytes, offset, value.Value); } }

新代码（v2.x）：

public void Serialize(ref MessagePackWriter writer, Int16? value, MessagePackSerializerOptions options) { if (value == null) { writer.WriteNil(); } else { writer.Write(value.Value); } }

从v2.x迁移到v3.x的关键变更

1. 适应AOT源生成默认启用

v3.x默认启用了AOT源生成，这意味着您需要：

• 将带有[MessagePackObject]特性的类型声明为partial：

  [MessagePackObject] public partial class MyDataClass { [Key(0)] public int Id { get; set; } }

• 自定义格式化器应声明为internal以自动包含在源生成的解析器中

2. 迁移配置文件

v3.x不再使用MessagePackAnalyzer.json文件，而是通过特性配置：

旧方式（v2.x）：MessagePackAnalyzer.json

{ "AssumedFormattableTypes": [ "MyNamespace.MyType1", "MyNamespace.MyType2" ] }

新方式（v3.x）：使用程序集特性

[assembly: MessagePackAssumedFormattable(typeof(MyNamespace.MyType1))] [assembly: MessagePackAssumedFormattable(typeof(MyNamespace.MyType2))]

3. 移除mpc CLI工具依赖

v3.x使用Roslyn源生成器替代了mpc工具，您需要：

1. 从构建脚本中移除所有mpc调用
2. 按照README中的AOT部分创建源生成的解析器

4. Unity用户特别注意事项

• 使用NuGetForUnity获取MessagePack包，而非直接下载源代码
• 确保Unity版本至少为2022.3.12f1

常见问题与解决方案

问题1：升级后编译错误"类型必须是partial"

解决方案：为所有带有[MessagePackObject]特性的类添加partial修饰符：

[MessagePackObject] public partial class MyClass { ... }

问题2：找不到LZ4MessagePackSerializer类

解决方案：使用MessagePackSerializerOptions配置压缩：

var options = MessagePackSerializerOptions.Standard .WithCompression(MessagePackCompression.Lz4BlockArray);

问题3：自定义格式化器不被识别

解决方案：确保自定义格式化器：

1. 实现IMessagePackFormatter<T>接口
2. 声明为internal
3. 使用[MessagePackKnownFormatter]特性标记

迁移后的验证步骤

升级完成后，建议执行以下验证步骤：

1. 运行单元测试：确保所有现有测试通过
2. 检查序列化兼容性：验证新版本能否正确反序列化旧版本生成的数据
3. 性能测试：对比升级前后的序列化/反序列化性能
4. 内存使用检查：使用内存分析工具确认没有内存泄漏

总结

从MessagePack-CSharp v1.x升级到最新版本虽然涉及一些API变更，但带来了显著的性能提升和功能增强。通过遵循本指南中的步骤，您可以平滑完成迁移过程。主要变化包括MessagePackSerializerOptions的引入、AOT源生成的默认启用以及配置方式的改进。

官方迁移文档：doc/migration.md

如果您在迁移过程中遇到任何问题，可以查阅项目的官方文档或提交issue获取帮助。祝您升级顺利！

【免费下载链接】MessagePack-CSharpExtremely Fast MessagePack Serializer for C#(.NET, .NET Core, Unity, Xamarin). / msgpack.org[C#]项目地址: https://gitcode.com/gh_mirrors/me/MessagePack-CSharp