在適用於 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 用戶端

JavaScript 用戶端的 MessagePack 支援是由 @microsoft/signalr-protocol-msgpack npm 套件提供。 在命令殼層中執行下列命令，以安裝套件：

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 物件。 這與將那些物件序列化為 short 物件的 C# 和 JavaScript 用戶端形成對比。 MessagePack 規格本身不會定義 char 物件的行為，因此由程式庫作者決定如何序列化它們。 用戶端之間的行為差異是因為我們用於實作的程式庫不同。

其他資源

• ASP.NET Core SignalR .NET 用戶端
• ASP.NET Core SignalR JavaScript 用戶端