Gunakan MessagePack Hub Protocol di SignalR untuk ASP.NET Core

Artikel ini mengasumsikan pembaca terbiasa dengan topik yang dibahas dalam Memulai ASP.NET Core SignalR.

Apa itu MessagePack?

MessagePack adalah format serialisasi biner yang cepat dan ringkas. Ini berguna ketika performa dan bandwidth menjadi perhatian karena menciptakan pesan yang lebih kecil daripada JSON. Pesan biner tidak dapat dibaca saat melihat jejak jaringan dan log kecuali byte diteruskan melalui parser MessagePack. SignalR memiliki dukungan bawaan untuk format MessagePack dan menyediakan API untuk digunakan klien dan server.

Mengonfigurasi MessagePack di server

Untuk mengaktifkan Protokol Hub MessagePack di server, instal Microsoft.AspNetCore.SignalR.Protocols.MessagePack paket di aplikasi Anda. Dalam metode , Startup.ConfigureServices tambahkan AddMessagePackProtocol ke AddSignalR panggilan untuk mengaktifkan dukungan MessagePack di server.

services.AddSignalR()
    .AddMessagePackProtocol();

Catatan

JSON diaktifkan secara default. Menambahkan MessagePack memungkinkan dukungan untuk klien JSON dan MessagePack.

Untuk menyesuaikan bagaimana MessagePack memformat data, AddMessagePackProtocol ambil delegasi untuk mengonfigurasi opsi. Dalam delegasi tersebut SerializerOptions , properti digunakan untuk mengonfigurasi opsi serialisasi MessagePack. Untuk informasi selengkapnya tentang cara kerja pemecah masalah, kunjungi pustaka MessagePack di MessagePack-CSharp. Atribut dapat digunakan pada objek yang ingin Anda serialkan untuk menentukan bagaimana atribut tersebut harus ditangani.

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

Peringatan

Kami sangat menyarankan untuk meninjau CVE-2020-5234 dan menerapkan patch yang direkomendasikan. Misalnya, memanggil .WithSecurity(MessagePackSecurity.UntrustedData) saat mengganti SerializerOptions.

Mengonfigurasi MessagePack pada klien

Catatan

JSON diaktifkan secara default untuk klien yang didukung. Klien hanya dapat mendukung satu protokol. Menambahkan dukungan MessagePack menggantikan protokol yang dikonfigurasi sebelumnya.

Klien .NET

Untuk mengaktifkan MessagePack di Klien .NET, instal Microsoft.AspNetCore.SignalR.Protocols.MessagePack paket dan panggil AddMessagePackProtocol di HubConnectionBuilder.

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

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

Catatan

Panggilan ini AddMessagePackProtocol mengambil delegasi untuk mengonfigurasi opsi seperti server.

Klien JavaScript

Dukungan MessagePack untuk klien JavaScript disediakan oleh paket npm @microsoft/signalr-protocol-msgpack . Instal paket dengan menjalankan perintah berikut dalam shell perintah:

npm install @microsoft/signalr-protocol-msgpack

Setelah menginstal paket npm, modul dapat digunakan langsung melalui pemuat modul JavaScript atau diimpor ke browser dengan mereferensikan file berikut:

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

File javaScript yang diperlukan berikut harus direferensikan dalam urutan yang ditunjukkan di bawah ini:

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

.withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol()) Menambahkan ke HubConnectionBuilder konfigurasi klien untuk menggunakan protokol MessagePack saat menyambungkan ke server.

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

Saat ini, tidak ada opsi konfigurasi untuk protokol MessagePack pada klien JavaScript.

Klien Java

Untuk mengaktifkan MessagePack dengan Java, instal com.microsoft.signalr.messagepack paket. Saat menggunakan Gradle, tambahkan baris berikut ke bagian dependencies file build.gradle :

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

Saat menggunakan Maven, tambahkan baris berikut di <dependencies> dalam elemen pom.xml file:

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

Panggil withHubProtocol(new MessagePackHubProtocol()) di HubConnectionBuilder.

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

Pertimbangan MessagePack

Ada beberapa masalah yang perlu diperhatikan saat menggunakan Protokol Hub MessagePack.

MessagePack peka huruf besar/kecil

Protokol MessagePack peka huruf besar/kecil. Misalnya, pertimbangkan kelas C# berikut:

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

Saat mengirim dari klien JavaScript, Anda harus menggunakan PascalCased nama properti, karena casing harus sama persis dengan kelas C#. Contohnya:

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

Menggunakan camelCased nama tidak akan terikat dengan benar ke kelas C#. Anda dapat mengatasinya dengan menggunakan Key atribut untuk menentukan nama yang berbeda untuk properti MessagePack. Untuk informasi selengkapnya, lihat dokumentasi MessagePack-CSharp.

DateTime.Kind tidak dipertahankan saat serialisasi/deserialisasi

Protokol MessagePack tidak menyediakan cara untuk mengodekan Kind DateTimenilai . Akibatnya, ketika mendeserialisasi tanggal, Protokol MessagePack Hub akan mengonversi ke format UTC jika DateTime.Kind sebaliknya DateTimeKind.Local tidak akan menyentuh waktu dan meneruskannya apa adanya. Jika Anda bekerja dengan DateTime nilai, sebaiknya konversi ke UTC sebelum mengirimkannya. Konversikan dari UTC ke waktu lokal saat Anda menerimanya.

Dukungan MessagePack di lingkungan kompilasi "sebelumnya"

Pustaka MessagePack-CSharp yang digunakan oleh klien .NET dan server menggunakan pembuatan kode untuk mengoptimalkan serialisasi. Akibatnya, ini tidak didukung secara default pada lingkungan yang menggunakan kompilasi "ahead-of-time" (seperti Xamarin iOS atau Unity). Dimungkinkan untuk menggunakan MessagePack di lingkungan ini dengan "pra-pembuatan" kode serializer/deserializer. Untuk informasi selengkapnya, lihat dokumentasi MessagePack-CSharp. Setelah membuat serializer sebelumnya, Anda dapat mendaftarkannya menggunakan delegasi konfigurasi yang diteruskan ke 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);
    });

Pemeriksaan jenis lebih ketat di MessagePack

Protokol Hub JSON akan melakukan konversi jenis selama deserialisasi. Misalnya, jika objek masuk memiliki nilai properti yang merupakan angka ({ foo: 42 }) tetapi properti pada kelas .NET berjenis string, nilai akan dikonversi. Namun, MessagePack tidak melakukan konversi ini dan akan melemparkan pengecualian yang dapat dilihat di log sisi server (dan di konsol):

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

Untuk informasi selengkapnya tentang batasan ini, lihat Masalah GitHub aspnet/SignalR#2937.

Karakter dan String di Java

Di klien java, char objek akan diserialisasikan sebagai objek satu karakter String . Ini berbeda dengan klien C# dan JavaScript, yang menserialisasikannya sebagai short objek. Spesifikasi MessagePack itu sendiri tidak menentukan perilaku untuk char objek, jadi terserah penulis pustaka untuk menentukan cara menserialisasikannya. Perbedaan perilaku antara klien kami adalah hasil dari pustaka yang kami gunakan untuk implementasi kami.

Sumber Daya Tambahan:

• ASP.NET Core SignalR .NET Client
• klien ASP.NET Core SignalR JavaScript