Freigeben über

Verwenden des Azure SignalR Management SDK

  • Artikel

Das Azure SignalR Management SDK hilft Ihnen, SignalR-Clients direkt über Azure SignalR Service zu verwalten, z. B. Übertragungsnachrichten. Daher kann dieses SDK unter anderem in serverlosen Umgebungen verwendet werden. Sie können dieses SDK verwenden, um SignalR-Clients zu verwalten, die mit Azure SignalR Service in einer beliebigen Umgebung verbunden sind, z. B. in einer Konsolen-App, in einer Azure-Funktion oder auf einem Webserver.

Hinweis

Anleitungen für Version 1.9.x des SDK und frühere Versionen finden Sie unter Azure SignalR Service Management SDK (Legacy). Sie sollten auch den Migrationsleitfaden lesen.

Features

Funktion Transient (vorübergehend) Beständig
Broadcast ✔️ ✔️
Übertragung außer einigen Clients ✔️ ✔️
An einen Client senden ✔️ ✔️
An Clients senden ✔️ ✔️
Senden an einen Benutzer ✔️ ✔️
An Benutzer*innen senden ✔️ ✔️
Senden an eine Gruppe ✔️ ✔️
An Gruppen senden ✔️ ✔️
An eine Gruppe mit Ausnahme einiger Clients senden ✔️ ✔️
Benutzer*in zu einer Gruppe hinzufügen ✔️ ✔️
Benutzer*in aus einer Gruppe entfernen ✔️ ✔️
Überprüfen, ob ein*e Benutzer*in in einer Gruppe ist ✔️ ✔️
Unterstützung mehrerer SignalR Service-Instanzen ❌ ✔️
Unterstützung von MessagePack-Clients ab Version 1.21.0 ab Version 1.20.0
Wiederholen eines vorübergehenden Fehlers ab Version 1.22.0 ❌

Exklusive Features der neuen API

Funktion Transient (vorübergehend) Beständig
Überprüfen, ob eine Verbindung besteht ✔️ ab Version 1.11
Überprüfen, ob eine Gruppe vorhanden ist ✔️ ab Version 1.11
Überprüfen, ob ein*e Benutzer*in vorhanden ist ✔️ ab Version 1.11
Schließen einer Clientverbindung ✔️ ab Version 1.11

  • Weitere Details zu verschiedenen Modi finden Sie hier.

  • Ein vollständiges Beispiel für das Management SDK finden Sie hier.

Verwendung

In diesem Abschnitt wird gezeigt, wie Sie das Management SDK verwenden.

Erstellen von Service Manager

Erstellen Sie Ihre Instanz von ServiceManager aus ServiceManagerBuilder:


var serviceManager = new ServiceManagerBuilder()
                    .WithOptions(option =>
                    {
                        option.ConnectionString = "<Your Azure SignalR Service Connection String>";
                    })
                    .WithLoggerFactory(loggerFactory)
                    .BuildServiceManager();

Sie können ServiceManager verwenden, um den Azure SignalR-Endpunktstatus zu überprüfen und den Diensthubkontext zu erstellen. Der folgende Abschnitt enthält Details zum Erstellen des Diensthubkontexts.

Um die Integrität des Azure SignalR-Endpunkts zu überprüfen, können Sie die ServiceManager.IsServiceHealthy-Methode verwenden. Wenn Sie über mehrere Azure SignalR-Endpunkte verfügen, wird nur der erste Endpunkt überprüft.

var health = await serviceManager.IsServiceHealthy(cancellationToken);

Erstellen des Diensthubkontexts

Erstellen Sie Ihre Instanz von ServiceHubContext aus ServiceManager:

var serviceHubContext = await serviceManager.CreateHubContextAsync("<Your Hub Name>",cancellationToken);

Aushandlung

In Standardmodus wird der Endpunkt /<Your Hub Name>/negotiate für die Aushandlung durch das Azure SignalR Service SDK verfügbar gemacht. SignalR-Clients erreichen diesen Endpunkt und leiten dann später zu Azure SignalR Service um.

Im serverlosen Modus wird empfohlen, einen Aushandlungsendpunkt zu hosten, um die Aushandlungsanforderung der SignalR-Clients zu verarbeiten und die Clients an Azure SignalR Service weiterzuleiten.

Tipp

Weitere Informationen zur Umleitung finden Sie im Aushandlungsprotokoll von SignalR.

Der Endpunkte und das Zugriffstoken sind nützlich, wenn Sie SignalR-Clients an Azure SignalR Service umleiten möchten.

Sie können die Instanz von ServiceHubContext verwenden, um die Endpunkt-URL und das entsprechende Zugriffstoken für SignalR-Clients zu generieren und eine Verbindung mit Azure SignalR Service herzustellen.

var negotiationResponse = await serviceHubContext.NegotiateAsync(new (){UserId = "<Your User Id>"});

Wenn Ihr Hubendpunkt http://<Your Host Name>/<Your Hub Name> ist, ist Ihr Aushandlungsendpunkt http://<Your Host Name>/<Your Hub Name>/negotiate. Sobald Sie den Aushandlungsendpunkt hosten, können Sie die SignalR-Clients verwenden, um folgendermaßen eine Verbindung mit Ihrem Hub herzustellen:

var connection = new HubConnectionBuilder().WithUrl("http://<Your Host Name>/<Your Hub Name>").Build();
await connection.StartAsync();

Das Beispiel zur Verwendung des Management SDK zum Umleiten von SignalR-Clients zu Azure SignalR Service finden Sie hier.

Senden von Nachrichten und Verwalten von Gruppen

Aus ServiceHubContextBuilder wird eine ServiceHubContext-Klasse erstellt, die IServiceHubContext implementiert und erweitert. Sie können sie verwenden, um Nachrichten an Ihre Clients zu senden und Ihre Gruppen zu verwalten.

try
{
    // Broadcast
    await hubContext.Clients.All.SendAsync(callbackName, obj1, obj2, ...);

    // Send to user
    await hubContext.Clients.User(userId).SendAsync(callbackName, obj1, obj2, ...);

    // Send to group
    await hubContext.Clients.Group(groupId).SendAsync(callbackName, obj1, obj2, ...);

    // add user to group
    await hubContext.UserGroups.AddToGroupAsync(userId, groupName);

    // remove user from group
    await hubContext.UserGroups.RemoveFromGroupAsync(userId, groupName);
}
finally
{
    await hubContext.DisposeAsync();
}

Stark typisierter Hub

Ein stark typisierter Hub ist ein Programmiermodell, das Sie Ihre Clientmethoden in eine Schnittstelle extrahieren kann, sodass Schreibfehler im Methodennamen oder das Übergeben der falschen Parametertypen vermieden werden können.

Nehmen Sie an, dass eine Clientmethode namens ReceivedMessage mit zwei Zeichenfolgenparametern vorliegt. Ohne stark typisierte Hubs übertragen Sie über hubContext.Clients.All.SendAsync("ReceivedMessage", user, message) an Clients. Bei stark typisierten Hubs definieren Sie zunächst eine Schnittstelle:

public interface IChatClient
{
    Task ReceiveMessage(string user, string message);
}

Anschließend erstellen Sie einen stark typisierten Hubkontext, der IHubContext<Hub<T>, T> implementiert, und T ist die Clientmethodenschnittstelle:

ServiceHubContext<IChatClient> serviceHubContext = await serviceManager.CreateHubContextAsync<IChatClient>(hubName, cancellationToken);

Schließlich könnten Sie die Methode direkt aufrufen:

await Clients.All.ReceiveMessage(user, message);

Mit Ausnahme des Unterschieds beim Senden von Nachrichten können Sie Gruppen mit ServiceHubContext<T> aushandeln oder verwalten, genau wie mit ServiceHubContext.

Weitere Informationen zu stark typisierten Hubs finden Sie in der ASP.NET Core-Dokumentation.

Transportart

Dieses SDK kann über zwei Transporttypen mit Azure SignalR Service kommunizieren:

  • Vorübergehend: Eine Azure SignalR Service-HTTP-Anforderung wird für jede gesendete Nachricht erstellt. Das SDK schließt die REST-API von Azure SignalR Service im Modus „Vorübergehend“ einfach ein. Das ist nützlich, wenn Sie keine WebSockets-Verbindung herstellen können.
  • Dauerhaft: Zuerst wird eine WebSockets-Verbindung erstellt, und dann werden alle Nachrichten in dieser Verbindung gesendet. Das ist nützlich, wenn Sie eine große Anzahl von Nachrichten senden.

Zusammenfassung der Serialisierungsverhalten der Argumente in Nachrichten

Serialisierung Transient (vorübergehend) Beständig
JSON-Standardbibliothek Newtonsoft.Json Genau wie bei ASP.NET Core SignalR:
Newtonsoft.Json für .NET Standard 2.0,
System.Text.Json für .NET Core App 3.1 und höher
Unterstützung von MessagePack-Clients ab Version 1.21.0 ab Version 1.20.0

JSON-Serialisierung

Im Management SDK werden die an Clients gesendeten Methodenargumente in JSON serialisiert. Es gibt verschiedene Möglichkeiten, die JSON-Serialisierung anzupassen. Diese Möglichkeiten werden in der Reihenfolge von den am meisten empfohlenen bis zu den am wenigsten empfohlenen vorgestellt.

ServiceManagerOptions.UseJsonObjectSerializer(ObjectSerializer objectSerializer)

Die am meisten empfohlene Methode ist die Verwendung einer allgemeinen abstrakten Klasse ObjectSerializer, da sie verschiedene JSON-Serialisierungsbibliotheken wie System.Text.Json und Newtonsoft.Json unterstützt und für alle Transporttypen gilt. In der Regel müssen Sie ObjectSerializer nicht selbst implementieren, da bereits JSON-Implementierungen für System.Text.Json und Newtonsoft.Json vorhanden sind.

  • Bei Verwendung von System.Text.Json als JSON-Verarbeitungsbibliothek verwendet die integrierte JsonObjectSerializer-Klasse System.Text.Json.JsonSerializer für die Serialisierung und Deserialisierung. Im Folgenden finden Sie ein Beispiel für die Verwendung der Camel-Case-Namensgebung für die JSON-Serialisierung:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new JsonObjectSerializer(new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase
        }));
    })
    .BuildServiceManager();

  • Wenn Sie Newtonsoft.Json als JSON-Verarbeitungsbibliothek verwenden, installieren Sie zuerst das Paket Microsoft.Azure.Core.NewtonsoftJson von NuGet mithilfe der .NET-CLI:

    dotnet add package Microsoft.Azure.Core.NewtonsoftJson

    Im Folgenden finden Sie ein Beispiel für die Verwendung der Camel-Case-Namensgebung mit NewtonsoftJsonObjectSerializer:

    var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.ConnectionString = "***";
        o.UseJsonObjectSerializer(new NewtonsoftJsonObjectSerializer(new JsonSerializerSettings()
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        }));
    })
    .BuildServiceManager();

  • Bei Verwendung anderer JSON-Verarbeitungsbibliotheken

    Sie können ObjectSerializer auch manuell implementieren. Die folgenden Links können hilfreich sein:

ServiceManagerBuilder.WithNewtonsoftJson(Action<NewtonsoftServiceHubProtocolOptions> configure)

Diese Methode ist nur für Newtonsoft.Json-Benutzer*innen vorgesehen. Im Folgenden finden Sie ein Beispiel für die Verwendung der Camel-Case-Namensgebung:

var serviceManager = new ServiceManagerBuilder()
    .WithNewtonsoftJson(o =>
    {
        o.PayloadSerializerSettings = new JsonSerializerSettings
        {
            ContractResolver = new CamelCasePropertyNamesContractResolver()
        };
    })
    .BuildServiceManager();
ServiceManagerOptions.JsonSerializerSettings (veraltet)

Diese Methode gilt nur für den Transporttyp „Vorübergehend“. Verwenden Sie dies nicht.

var serviceManager = new ServiceManagerBuilder()
    .WithOptions(o =>
    {
        o.JsonSerializerSettings.ContractResolver = new CamelCasePropertyNamesContractResolver();
    })
    .BuildServiceManager();

MessagePack-Serialisierung

  1. Sie müssen das Microsoft.AspNetCore.SignalR.Protocols.MessagePack-Paket installieren.

  2. So fügen Sie ein MessagePack-Protokoll parallel zum JSON-Standardprotokoll hinzu:

    var serviceManagerBuilder = new ServiceManagerBuilder()
    .AddHubProtocol(new MessagePackHubProtocol());

  3. Um die Hubprotokolle vollständig zu steuern, können Sie Folgendes verwenden:

        var serviceManagerBuilder = new ServiceManagerBuilder()
        .WithHubProtocols(new MessagePackHubProtocol(), new JsonHubProtocol());

    WithHubProtocols löscht zuerst die vorhandenen Protokolle und fügt dann die neuen Protokolle hinzu. Sie können diese Methode auch verwenden, um das JSON-Protokoll zu entfernen und nur MessagePack zu verwenden.

Für den Modus „Vorübergehend“ konvertiert die Dienstseite standardmäßig JSON-Nutzdaten in MessagePack-Nutzdaten. Das ist die Legacymethode zur Unterstützung von MessagePack. Es wird jedoch empfohlen, ein MessagePack-Hubprotokoll explizit hinzuzufügen, da die Legacymethode möglicherweise nicht wie erwartet funktioniert.

Wiederholen von HTTP-Anforderungen

Für den Modus Vorübergehend bietet dieses SDK die Möglichkeit, Anforderungen automatisch erneut zu senden, wenn vorübergehende Fehler auftreten, solange die Anforderungen idempotent sind. Um diese Funktion zu aktivieren, können Sie die Eigenschaft ServiceManagerOptions.RetryOptions verwenden.

Insbesondere werden die folgenden Arten von Anforderungen wiederholt:

  • Bei Nachrichtenanforderungen, die Nachrichten an SignalR-Clients senden, wiederholt das SDK die Anforderung, wenn der HTTP-Antwortstatuscode größer als 500 ist. Wenn der HTTP-Antwortcode gleich 500 ist, ist möglicherweise ein Timeout auf der Dienstseite aufgetreten, und das Wiederholen der Anforderung kann zu doppelten Nachrichten führen.

  • Für andere Arten von Anforderungen, z. B. das Hinzufügen einer Verbindung zu einer Gruppe, wiederholt das SDK die Anforderung unter den folgenden Bedingungen:

    1. Der HTTP-Antwortstatuscode befindet sich im 5xx-Bereich, oder die Anforderung weist den Statuscode 408 (Anforderungstimeout) auf.
    2. Ein Anforderungstimeout ist aufgetreten, weil die Anforderung länger als das in ServiceManagerOptions.HttpClientTimeout konfigurierte Timeout gedauert hat.

Das SDK kann nur idempotente Anforderungen wiederholen, bei denen es sich um Anforderungen handelt, die keine andere Auswirkung haben, wenn sie wiederholt werden. Wenn Ihre Anforderungen nicht idempotent sind, müssen Sie Wiederholungen möglicherweise manuell durchführen.

Nächste Schritte

In diesem Artikel erfahren Sie, wie Sie SignalR Service in Ihren Anwendungen verwenden. Weitere Informationen zu SignalR Service finden Sie in den folgenden Artikeln.

Ausführliche Informationen zu Azure SignalR Service

Schnellstart: Erstellen eines Chatrooms mit SignalR Service