在 ASP.NET Core SignalR 中使用 MessagePack 中心协议

本文假定读者熟悉 ASP.NET Core SignalR 入门中涵盖的主题。

什么是 MessagePack？

MessagePack 是一种快速而紧凑的二进制序列化格式。 当担忧性能和带宽问题时，这很有用，因为它创建的消息比 JSON 创建的小。 查看网络跟踪和日志时，二进制消息不可读取，除非这些字节是通过 MessagePack 分析器传递的。 SignalR 为 MessagePack 格式提供内置支持，并提供 API 供客户端和服务器使用。

在服务器上配置 MessagePack

若要在服务器上启用 MessagePack 中心协议，请在应用中安装 Microsoft.AspNetCore.SignalR.Protocols.MessagePack 包。 在 Startup.ConfigureServices 方法中，将 AddMessagePackProtocol 添加到 AddSignalR 调用以在服务器上启用 MessagePack 支持。

services.AddSignalR()
    .AddMessagePackProtocol();

注意

JSON 默认启用。 添加 MessagePack 可同时支持 JSON 和 MessagePack 客户端。

若要自定义 MessagePack 如何设置数据格式，AddMessagePackProtocol 可接受委托来配置选项。 在该委托中，SerializerOptions 属性用于配置 MessagePack 序列化选项。 有关解析程序工作方式的详细信息，请访问位于 MessagePack-CSharp 的 MessagePack 库。 可以对要序列化的对象使用属性，以定义应如何处理这些对象。

services.AddSignalR()
    .AddMessagePackProtocol(options =>
    {
        options.SerializerOptions = MessagePackSerializerOptions.Standard
            .WithResolver(new CustomResolver())
            .WithSecurity(MessagePackSecurity.UntrustedData);
    });

警告

强烈建议查看 CVE-2020-5234 并应用推荐的修补程序。 例如，替换 SerializerOptions 时调用 .WithSecurity(MessagePackSecurity.UntrustedData)。

在客户端上配置 MessagePack

注意

JSON 在支持的客户端启用上默认启用。 客户端只能支持单个协议。 添加 MessagePack 支持将会替换之前配置的任何协议。

.NET 客户端

若要在 .NET 客户端中启用 MessagePack，请安装 Microsoft.AspNetCore.SignalR.Protocols.MessagePack 包，并在 HubConnectionBuilder 上调用 AddMessagePackProtocol。

using Microsoft.AspNetCore.SignalR.Client;
using Microsoft.Extensions.DependencyInjection;

var hubConnection = new HubConnectionBuilder()
                        .WithUrl("/chathub")
                        .AddMessagePackProtocol()
                        .Build();

注意

此 AddMessagePackProtocol 调用接受委托来配置选项，就像服务器一样。

JavaScript 客户端

@microsoft/signalr-protocol-msgpack npm 包提供对 JavaScript 客户端的 MessagePack 支持。 在命令行界面中执行以下命令来安装包：

npm install @microsoft/signalr-protocol-msgpack

安装 npm 包后，可以通过 JavaScript 模块加载程序直接使用该模块，或引用以下文件将该模块导入浏览器：

node_modules\@microsoft\signalr-protocol-msgpack\dist\browser\signalr-protocol-msgpack.js

必须按如下所示的顺序引用以下必需的 JavaScript 文件：

<script src="~/lib/signalr/signalr.js"></script>
<script src="~/lib/signalr/signalr-protocol-msgpack.js"></script>

如果将 .withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol()) 添加到 HubConnectionBuilder，则会将客户端配置为在连接到服务器时使用 MessagePack 协议。

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol())
    .build();

目前，JavaScript 客户端上没有 MessagePack 协议的配置选项。

Java 客户端

若要使用 Java 启用 MessagePack，请安装 com.microsoft.signalr.messagepack 包。 使用 Gradle 时，将以下行添加到 build.gradle 文件的 dependencies 部分：

implementation 'com.microsoft.signalr.messagepack:signalr-messagepack:5.0.0'

使用 Maven 时，将以下行添加到 pom.xml 文件的 <dependencies> 元素中：

<dependency>
    <groupId>com.microsoft.signalr.messagepack</groupId>
    <artifactId>signalr</artifactId>
    <version>5.0.0</version>
</dependency>

在 HubConnectionBuilder 上调用 withHubProtocol(new MessagePackHubProtocol())。

HubConnection messagePackConnection = HubConnectionBuilder.create("YOUR HUB URL HERE")
    .withHubProtocol(new MessagePackHubProtocol())
    .build();

MessagePack 注意事项

使用 MessagePack 中心协议时，需要注意几个问题。

MessagePack 区分大小写

MessagePack 协议区分大小写。 例如，请考虑以下 C# 类：

public class ChatMessage
{
    public string Sender { get; }
    public string Message { get; }
}

从 JavaScript 客户端发送时，必须使用 PascalCased 属性名称，因为大小写必须与 C# 类完全匹配。 例如：

connection.invoke("SomeMethod", { Sender: "Sally", Message: "Hello!" });

使用 camelCased 名称无法正确绑定到 C# 类。 可使用 Key 属性为 MessagePack 属性指定不同的名称来解决此问题。 有关详细信息，请参阅 MessagePack-CSharp 文档。

序列化/反序列化时不保留 DateTime.Kind

MessagePack 协议不提供对 DateTime 的 Kind 值进行编码的方法。 因此，在对日期进行反序列化时，如果 DateTime.Kind 为 DateTimeKind.Local，MessagePack 中心协议会将其转换为 UTC 格式，否则它将不会触及时间并按原样传递。 如果你使用的是 DateTime 值，建议在发送这些值之前将它们转换为 UTC。 当你接收到它们时，将它们从 UTC 转换为本地时间。

“预先”编译环境中的 MessagePack 支持

.NET 客户端和服务器使用的 MessagePack-CSharp 库使用代码生成来优化序列化。 因此，默认情况下，它在使用“预先”编译的环境（如 Xamarin iOS 或 Unity）中不受支持。 可通过“预生成”序列化程序/反序列化程序代码，在这些环境中使用 MessagePack。 有关详细信息，请参阅 MessagePack-CSharp 文档。 预生成序列化程序后，可使用传递给 AddMessagePackProtocol 的配置委托注册它们：

services.AddSignalR()
    .AddMessagePackProtocol(options =>
    {
        StaticCompositeResolver.Instance.Register(
            MessagePack.Resolvers.GeneratedResolver.Instance,
            MessagePack.Resolvers.StandardResolver.Instance
        );
        options.SerializerOptions = MessagePackSerializerOptions.Standard
            .WithResolver(StaticCompositeResolver.Instance)
            .WithSecurity(MessagePackSecurity.UntrustedData);
    });

MessagePack 中的类型检查更加严格

JSON 中心协议将在反序列化过程中执行类型转换。 例如，如果传入对象的属性值为数字 ({ foo: 42 })，但 .NET 类的属性类型为 string，则该值将被转换。 但是，MessagePack 不会执行此转换并将引发异常，该异常可在服务器端日志（和控制台）中查看：

InvalidDataException: Error binding arguments. Make sure that the types of the provided values match the types of the hub method being invoked.

有关此限制的详细信息，请参阅 GitHub 问题 aspnet/SignalR#2937。

Java 中的字符和字符串

在 Java 客户端中，char 对象将被序列化为单字符 String 对象。 这与 C# 和 JavaScript 客户端相反，后者将它们序列化为 short 对象。 MessagePack 规范本身不会定义 char 对象的行为，因此由库作者决定如何序列化它们。 客户端之间的行为差异是由我们用于实现的库造成的。

其他资源

• ASP.NET Core SignalR .NET 客户端
• ASP.NET Core SignalR JavaScript 客户端