Usare il protocollo hub MessagePack in SignalR per ASP.NET Core

Questo articolo presuppone che il lettore abbia familiarità con gli argomenti trattati in Introduzione a ASP.NET Core SignalR.

Che cos'è MessagePack?

MessagePack è un formato di serializzazione binario veloce e compatto. È utile quando le prestazioni e la larghezza di banda sono un problema perché crea messaggi più piccoli rispetto JSa ON. I messaggi binari sono illeggibili quando si esaminano le tracce di rete e i log, a meno che i byte non vengano passati tramite un parser MessagePack. SignalR include il supporto predefinito per il formato MessagePack e fornisce API per il client e il server da usare.

Configurare MessagePack nel server

Per abilitare il protocollo hub MessagePack nel server, installare il Microsoft.AspNetCore.SignalR.Protocols.MessagePack pacchetto nell'app. Startup.ConfigureServices Nel metodo aggiungere AddMessagePackProtocol alla AddSignalR chiamata per abilitare il supporto messagePack nel server.

services.AddSignalR()
    .AddMessagePackProtocol();

Nota

JSON è abilitato per impostazione predefinita. L'aggiunta di MessagePack abilita il supporto per JSi client ON e MessagePack.

Per personalizzare il modo in cui MessagePack formatta i dati, AddMessagePackProtocol accetta un delegato per la configurazione delle opzioni. In tale delegato, la SerializerOptions proprietà viene utilizzata per configurare le opzioni di serializzazione messagePack. Per altre informazioni sul funzionamento dei resolver, visitare la libreria MessagePack in MessagePack-CSharp. Gli attributi possono essere usati negli oggetti da serializzare per definire la modalità di gestione.

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

Avviso

È consigliabile esaminare CVE-2020-5234 e applicare le patch consigliate. Ad esempio, chiamando .WithSecurity(MessagePackSecurity.UntrustedData) quando si sostituisce .SerializerOptions

Configurare MessagePack nel client

Nota

JSON è abilitato per impostazione predefinita per i client supportati. I client possono supportare un solo protocollo. L'aggiunta del supporto di MessagePack sostituisce tutti i protocolli configurati in precedenza.

Client .NET

Per abilitare MessagePack nel client .NET, installare il Microsoft.AspNetCore.SignalR.Protocols.MessagePack pacchetto e chiamare AddMessagePackProtocol su HubConnectionBuilder.

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

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

Nota

Questa AddMessagePackProtocol chiamata accetta un delegato per configurare le opzioni esattamente come il server.

Client JavaScript

Il supporto di MessagePack per il client JavaScript viene fornito dal pacchetto npm @microsoft/signalr-protocol-msgpack . Installare il pacchetto eseguendo il comando seguente in una shell dei comandi:

npm install @microsoft/signalr-protocol-msgpack

Dopo aver installato il pacchetto npm, il modulo può essere usato direttamente tramite un caricatore di moduli JavaScript o importato nel browser facendo riferimento al file seguente:

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

Nell'ordine indicato di seguito è necessario fare riferimento ai file javaScript seguenti:

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

L'aggiunta .withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol())HubConnectionBuilder a configura il client per l'uso del protocollo MessagePack durante la connessione a un server.

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

Al momento, non sono disponibili opzioni di configurazione per il protocollo MessagePack nel client JavaScript.

Client Java

Per abilitare MessagePack con Java, installare il com.microsoft.signalr.messagepack pacchetto. Quando si usa Gradle, aggiungere la riga seguente alla dependencies sezione del file build.gradle :

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

Quando si usa Maven, aggiungere le righe seguenti all'interno dell'elemento <dependencies> del pom.xml file:

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

Chiamare withHubProtocol(new MessagePackHubProtocol()) su HubConnectionBuilder.

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

Considerazioni su MessagePack

Esistono alcuni problemi da tenere presenti quando si usa il protocollo hub MessagePack.

MessagePack fa distinzione tra maiuscole e minuscole

Il protocollo MessagePack fa distinzione tra maiuscole e minuscole. Si consideri ad esempio la classe C# seguente:

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

Quando si invia dal client JavaScript, è necessario usare PascalCased i nomi delle proprietà, perché la combinazione di maiuscole e minuscole deve corrispondere esattamente alla classe C#. Ad esempio:

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

L'uso dei camelCased nomi non verrà associato correttamente alla classe C#. È possibile risolvere questo problema usando l'attributo Key per specificare un nome diverso per la proprietà MessagePack. Per altre informazioni, vedere la documentazione di MessagePack-CSharp.

DateTime.Kind non viene mantenuto durante la serializzazione/deserializzazione

Il protocollo MessagePack non fornisce un modo per codificare il Kind valore di un oggetto DateTime. Di conseguenza, quando si deserializza una data, il protocollo dell'hub MessagePack verrà convertito nel formato UTC se in DateTime.KindDateTimeKind.Local caso contrario non tocca l'ora e lo passerà così com'è. Se si utilizzano DateTime valori, è consigliabile eseguire la conversione in formato UTC prima di inviarli. Convertirli dall'ora UTC all'ora locale quando li ricevi.

Supporto di MessagePack nell'ambiente di compilazione "in anticipo"

La libreria MessagePack-CSharp usata dal client e dal server .NET usa la generazione di codice per ottimizzare la serializzazione. Di conseguenza, non è supportato per impostazione predefinita in ambienti che usano la compilazione "in anticipo", ad esempio Xamarin iOS o Unity. È possibile usare MessagePack in questi ambienti "pregenerando" il codice serializzatore/deserializzatore. Per altre informazioni, vedere la documentazione di MessagePack-CSharp. Dopo aver pregenerato i serializzatori, è possibile registrarli usando il delegato di configurazione passato a 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);
    });

I controlli dei tipi sono più rigorosi in MessagePack

Il JSprotocollo ON Hub eseguirà conversioni di tipi durante la deserializzazione. Ad esempio, se l'oggetto in ingresso ha un valore di proprietà che è un numero ({ foo: 42 }) ma la proprietà nella classe .NET è di tipo string, il valore verrà convertito. MessagePack, tuttavia, non esegue questa conversione e genererà un'eccezione che può essere visualizzata nei log lato server (e nella console):

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

Per altre informazioni su questa limitazione, vedere Problema di GitHub aspnet/SignalR#2937.

Caratteri e stringhe in Java

Nel client Java gli char oggetti verranno serializzati come oggetti un carattere String . Questo è in contrasto con il client C# e JavaScript, che li serializza come short oggetti. La specifica MessagePack stessa non definisce il comportamento per char gli oggetti, quindi spetta all'autore della libreria determinare come serializzarle. La differenza di comportamento tra i client è il risultato delle librerie usate per le implementazioni.

Risorse aggiuntive

• client .NET di ASP.NET Core SignalR
• client JavaScript di ASP.NET Core SignalR