MessagePack-CSharp从v2迁移到v3的完整指南

MessagePack-CSharp从v2迁移到v3的完整指南

MessagePack-CSharp Extremely Fast MessagePack Serializer for C#(.NET, .NET Core, Unity, Xamarin). / msgpack.org[C#] 项目地址: https://gitcode.com/gh_mirrors/me/MessagePack-CSharp

前言

MessagePack-CSharp是一个高效的二进制序列化库，在v3版本中引入了重大改进。本文将详细介绍从v2迁移到v3的关键变化、注意事项和迁移步骤，帮助开发者顺利完成升级。

核心变化概述

v3版本最显著的改进是默认启用了AOT(提前编译)源代码生成功能。新的源代码生成格式化器与之前版本运行时生成的动态格式化器性能相当，但存在一些特有的限制。

主要破坏性变更

1. 分析器配置方式变更

v2版本使用MessagePackAnalyzer.json文件进行配置，v3改为使用以下特性：

• GeneratedMessagePackResolverAttribute
• MessagePackKnownFormatterAttribute
• MessagePackAssumedFormattableAttribute

2. AOT生成工具变更

v2使用mpc命令行工具生成AOT格式化器和解析器，v3改为使用Roslyn源代码生成器自动生成。

3. 类型可见性要求

自定义的IMessagePackFormatter<T>实现现在需要声明为internal，以便自动包含在源代码生成的解析器中。

4. 部分类要求

使用[MessagePackObject]注解的类型应声明为partial，以便源代码生成的格式化器可以访问私有/受保护成员。

5. Unity支持变更

• 不再支持Unity 2021.3，最低要求版本为2022.3.12f1
• 推荐使用NuGetForUnity获取MessagePack包，而不是下载源代码zip文件

迁移步骤详解

迁移MessagePackAnalyzer.json配置

1. 为json文件中列出的每个类型添加程序集级特性：

   [assembly: MessagePackAssumedFormattable(typeof(MyType1))]
   

2. 删除原有的MessagePackAnalyzer.json文件

从mpc迁移到源代码生成

1. 移除所有调用mpc的构建脚本
2. 创建源代码生成的解析器：
   • 确保使用.NET SDK 6.0或更高版本构建
   • 遵循AOT文档中的指导创建解析器

分析器增强

v3版本将原本可选的MessagePackAnalyzer包变为必需依赖项，这意味着升级后可能会看到新的编译诊断信息。v3还新增了许多诊断提供程序，为处理新的源代码生成格式化器提供专门帮助。

最佳实践建议

1. 类型设计：为所有需要序列化的类型添加partial修饰符
2. 可见性控制：将自定义格式化器设为internal
3. Unity项目：尽早升级到支持的Unity版本
4. 构建环境：确保使用.NET 6+ SDK构建项目
5. 渐进迁移：可以先在测试环境中验证兼容性

常见问题解答

Q: 为什么需要将类型声明为partial？
A: 源代码生成器需要能够扩展类型定义以生成高效的序列化代码，partial声明允许这种扩展。

Q: 自定义格式化器为什么需要是internal？
A: 这是源代码生成解析器自动发现和包含格式化器的必要条件。

Q: Unity项目迁移需要注意什么？
A: 主要注意Unity版本要求和包获取方式的变更，建议先在测试项目中验证。

总结

MessagePack-CSharp v3通过引入源代码生成技术，提供了更高效的序列化方案。虽然迁移过程需要一些调整，但这些改进为性能优化和开发体验带来了显著提升。按照本文指南，开发者可以顺利完成从v2到v3的迁移。

MessagePack-CSharp Extremely Fast MessagePack Serializer for C#(.NET, .NET Core, Unity, Xamarin). / msgpack.org[C#] 项目地址: https://gitcode.com/gh_mirrors/me/MessagePack-CSharp