Použití protokolu Centra MessagePack pro SignalR ASP.NET Core

Tento článek předpokládá, že čtenář je obeznámen s tématy popsanými v tématu Začínáme s ASP.NET Core SignalR.

Co je MessagePack?

MessagePack je rychlý a kompaktní binární serializační formát. Je užitečné, když se jedná o výkon a šířku pásma, protože vytváří menší zprávy než JSON. Binární zprávy jsou při pohledu na trasování sítě a protokoly nečitelné, pokud nejsou bajty předány prostřednictvím analyzátoru MessagePack. SignalR má integrovanou podporu pro formát MessagePack a poskytuje rozhraní API pro použití klienta a serveru.

Konfigurace balíčku MessagePack na serveru

Pokud chcete na serveru povolit protokol MessagePack Hub, nainstalujte Microsoft.AspNetCore.SignalR.Protocols.MessagePack balíček do aplikace. Startup.ConfigureServices V metodě přidejte AddMessagePackProtocol do AddSignalR volání povolení podpory MessagePack na serveru.

services.AddSignalR()
    .AddMessagePackProtocol();

Poznámka:

Json je ve výchozím nastavení povolený. Přidání MessagePacku umožňuje podporu pro klienty JSON i MessagePack.

Pokud chcete přizpůsobit, jak MessagePack formátuje data, AddMessagePackProtocol přebírá delegáta pro konfiguraci možností. V daném delegátu se SerializerOptions vlastnost používá ke konfiguraci možností serializace MessagePack. Další informace o tom, jak překladače fungují, naleznete v knihovně MessagePack na MessagePack-CSharp. Atributy lze použít u objektů, které chcete serializovat, a definovat, jak mají být zpracovány.

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

Upozorňující

Důrazně doporučujeme zkontrolovat CVE-2020-5234 a použít doporučené opravy. Například volání .WithSecurity(MessagePackSecurity.UntrustedData) při nahrazení .SerializerOptions

Konfigurace balíčku MessagePack v klientovi

Poznámka:

Pro podporované klienty je ve výchozím nastavení povolený JSON. Klienti můžou podporovat pouze jeden protokol. Přidání podpory MessagePacku nahrazuje všechny dříve nakonfigurované protokoly.

Klient .NET

Chcete-li povolit MessagePack v klientovi .NET, nainstalujte Microsoft.AspNetCore.SignalR.Protocols.MessagePack balíček a volání AddMessagePackProtocol .HubConnectionBuilder

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

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

Poznámka:

Toto AddMessagePackProtocol volání přebírá delegáta pro konfiguraci možností stejně jako server.

Javascriptový klient

Podpora MessagePacku pro klienta JavaScriptu je poskytována balíčkem @microsoft/signalr-protocol-msgpack npm. Nainstalujte balíček spuštěním následujícího příkazu v příkazovém prostředí:

npm install @microsoft/signalr-protocol-msgpack

Po instalaci balíčku npm je možné modul použít přímo přes zavaděč modulu JavaScript nebo importovat do prohlížeče odkazováním na následující soubor:

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

Následující požadované soubory javaScriptu musí být odkazovány v uvedeném pořadí:

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

Přidání .withHubProtocol(new signalR.protocols.msgpack.MessagePackHubProtocol()) do HubConnectionBuilder konfigurace klienta pro použití protokolu MessagePack při připojování k serveru.

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

V tuto chvíli neexistují žádné možnosti konfigurace protokolu MessagePack v javascriptovém klientovi.

Java klient

Pokud chcete povolit MessagePack s Javou com.microsoft.signalr.messagepack , nainstalujte balíček. Pokud používáte Gradle, přidejte do dependencies oddílu souboru build.gradle následující řádek:

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

Při použití Mavenu přidejte do elementu <dependencies> souboru následující řádkypom.xml:

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

Zavolejte withHubProtocol(new MessagePackHubProtocol()) .HubConnectionBuilder

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

Důležité informace o balíčku MessagePack

Při použití protokolu MessagePack Hub je potřeba mít na paměti několik problémů.

MessagePack rozlišují malá a velká písmena.

V protokolu MessagePack se rozlišují malá a velká písmena. Představte si například následující třídu jazyka C#:

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

Při odesílání z klienta JavaScriptu musíte použít PascalCased názvy vlastností, protože velikost písmen musí přesně odpovídat třídě jazyka C#. Příklad:

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

Použití camelCased názvů nebude správně svázané s třídou jazyka C#. Tento problém můžete obejít pomocí atributu Key , který určuje jiný název vlastnosti MessagePack. Další informace najdete v dokumentaci MessagePack-CSharp.

DateTime.Kind se nezachová při serializaci/deserializaci

Protokol MessagePack neposkytuje způsob kódování Kind hodnoty DateTime. V důsledku toho se při deserializaci data protokol Centra MessagePack převede na formát UTC, pokud DateTime.Kind je DateTimeKind.Local jinak nedotkne času a předá ho tak, jak je. Pokud pracujete s DateTime hodnotami, doporučujeme před jejich odesláním převést na UTC. Převeďte je z UTC na místní čas, když je obdržíte.

Podpora MessagePacku v prostředí kompilace s předstihem

Knihovna MessagePack-CSharp používaná klientem a serverem .NET používá generování kódu k optimalizaci serializace. V důsledku toho se ve výchozím nastavení nepodporuje v prostředích, která používají kompilaci s předstihem, jako je uživatelské rozhraní multiplatformních aplikací NET (.NET MAUI) nebo Unity. MessagePack je možné v těchto prostředích použít "předgenerováním" serializátoru/deserializátoru. Další informace najdete v dokumentaci MessagePack-CSharp. Jakmile serializátory předem vygenerujete, můžete je zaregistrovat pomocí delegáta konfigurace předaného do 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);
    });

Kontroly typů jsou v balíčku MessagePack přísnější.

Protokol CENTRA JSON provede převody typů během deserializace. Pokud například příchozí objekt má hodnotu vlastnosti, která je číslo ({ foo: 42 }), ale vlastnost třídy .NET je typu string, hodnota bude převedena. MessagePack však tento převod neprovádí a vyvolá výjimku, která se dá zobrazit v protokolech na straně serveru (a v konzole):

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

Další informace o tomto omezení najdete v tématu Problém s GitHubem aspnet/SignalR#2937.

Znaky a řetězce v Javě

V klientovi char Java budou objekty serializovány jako objekty s jedním znakem String . To je na rozdíl od klienta C# a JavaScriptu, který je serializuje jako short objekty. Samotná specifikace MessagePack nedefinuje chování pro char objekty, takže je na autor knihovny, aby určil, jak je serializovat. Rozdíl v chování mezi našimi klienty je výsledkem knihoven, které jsme použili pro naše implementace.

Další materiály

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