MessagePack for CLI 使用与技术文档

一、安装指南

MessagePack for CLI 的二进制文件通过 NuGet 包 MsgPack.Cli 进行分发。安装步骤如下：

1. 从 GitHub Release 页面 下载相应的 *.zip 文件。
2. 解压下载的文件。
3. 在 bin 目录下可以找到相应的二进制文件（DLL）。对于 mono，可以使用 net461 或 net35 版本的二进制文件；对于 Unity，unity3d 版本的二进制文件是合适的。

二、项目使用说明

MessagePack for CLI 是用于 CLI（Common Language Infrastructure）实现的序列化/反序列化库，例如 .NET Framework、Silverlight、Mono（包括 Moonlight）。这个库可以从所有符合 CLS（Common Language Specification）的语言中使用，如 C#、F#、Visual Basic、Iron Python、Iron Ruby、PowerShell、C++/CLI 等。

使用方法如下：

1. 通过 MessagePackSerializer.Get 泛型方法创建序列化器。此方法也会创建依赖类型的序列化器。
2. 按以下方式调用序列化器：
   • 使用 Pack 方法将目标对象序列化到 Stream 中。
   • 使用 Unpack 方法从 Stream 中反序列化对象。

// 创建序列化器。
var serializer = MessagePackSerializer.Get<T>();
// 将对象序列化到流中。
serializer.Pack(stream, obj);
// 从流中反序列化对象。
var unpackedObject = serializer.Unpack(stream);

' 创建序列化器。
Dim serializer = MessagePackSerializer.Get(Of T)()
' 将对象序列化到流中。
serializer.Pack(stream, obj)
' 从流中反序列化对象。
Dim unpackedObject = serializer.Unpack(stream)

在生产环境中，您应该实例化自己的 SerializationContext 并管理其生命周期。将 SerializationContext 视为单例是一个好主意，因为它是线程安全的。

三、项目API使用文档

详细的项目API使用文档，请参考 wiki。

四、项目安装方式

对于 .NET Framework

1. 安装 Visual Studio 2017（社区版即可）和 2015（用于构建 MsgPack.Windows.sln）。

   • 必须安装 .NET Framework 3.5、4.x、.NET Core 以及 Xamarin 开发工具以成功构建所有版本。如果不希望安装这些选项，可以在 *.csproj 文件中编辑 <TargetFrameworks> 元素以排除不需要的平台。

2. 安装最新的 .NET Core SDK。

3. 使用 Visual Studio 开发者命令提示符运行以下命令：

   msbuild MsgPack.sln /t:Restore
   msbuild MsgPack.sln
   

   或者（对于 Unity 3D 版本）：

   msbuild MsgPack.compats.sln /t:Restore
   msbuild MsgPack.compats.sln
   

   或者（对于 Windows Runtime/Phone 版本和 Silverlight 5 版本）：

   msbuild MsgPack.Windows.sln /t:Restore
   msbuild MsgPack.Windows.sln
   

   或者（对于 Xamarin 单元测试，必须在局域网中的 Mac 机器上安装 Xamarin Business 或更高版本的许可证）：

   msbuild MsgPack.Xamarin.sln /t:Restore
   msbuild MsgPack.Xamarin.sln
   

   或者在你的 IDE 中打开上述解决方案文件，并在其中运行构建命令。

对于 Mono

1. 安装最新的 Mono 和 .NET Core SDK。
2. 现在，可以使用上述说明和最新的 Mono 中的 msbuild 命令来构建 MsgPack.sln 和 MsgPack.Xamarin.sln。注意，xbuild 不支持最新的 csproj 格式，因此无法使用。

Unity 3D 项目的自定义构建

首先，GitHub Release 页面上有二进制版本，应该使用它来节省时间。由于我们无法保证源代码组织的兼容性，可能会添加或删除非公共类型或成员，这可能会导致源代码构建中断。如果您要导入源代码，必须仅包含 MsgPack.Unity3D.csproj 中描述的内容。如果您要使用 ".NET 2.0 Subset" 设置，必须仅使用 MsgPack.Unity3D.CorLibOnly.csproj 文件，并定义 CORLIB_ONLY 编译器常量。

Xamarin Android 测试

如果在 Windows 上运行，建议使用 HXM 而不是基于 Hyper-V 的模拟器。可以通过以下命令在管理员权限的 PowerShell 中禁用 Hyper-V：

Disable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-Hypervisor

如果想要重新启用 Hyper-V（例如，为了在 Windows 上运行 Docker 等），可以在管理员权限的 PowerShell 中使用以下命令：

Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V-Hypervisor

Xamarin Android 故障排除提示

• 问：Javac 显示编译错误。
  • 答：重新构建测试项目，然后再次运行。

Xamarin iOS 测试

必须在您的 Mac 设备上创建供应配置文件。有关详细信息，请参阅 Xamarin 文档关于供应。

以下是当前 iOS 测试的束标识符：

• org.msgpack.msgpack-cli-xamarin-ios-test
• org.msgpack.msgpack-cli-xamarin-ios-test-packer
• org.msgpack.msgpack-cli-xamarin-ios-test-unpacker
• org.msgpack.msgpack-cli-xamarin-ios-test-unpacking
• org.msgpack.msgpack-cli-xamarin-ios-test-timestamp
• org.msgpack.msgpack-cli-xamarin-ios-test-arrayserialization
• org.msgpack.msgpack-cli-xamarin-ios-test-mapserialization

注意，一些基于反射的序列化器测试由于 AOT 相关限制而失败。

Xamarin iOS 故障排除提示

首先查看 Xamarin 的官方故障排除文档。

• 问：运行单元测试项目时发生错误。
  • 答：重新构建项目并重新运行，或者重新登录您的 Mac，然后再次尝试。
• 问：英文难以阅读。
  • 答：可以通过在 URL 路径中将 {region}-{lang} 作为第一部分来阅读本地化的 Xamarin 文档，例如 https://developer.xamarin.com/ja-jp/guides/...。