Freigeben über


SignalR-Konfiguration in ASP.NET Core

In diesem Artikel wird die ASP.NET Core SignalR-Konfiguration behandelt.

Anleitungen zu BlazorSignalR, die Anleitungen in diesem Artikel ergänzen oder ersetzen, finden Sie im Leitfaden zu ASP.NET Core-BlazorSignalR.

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die JSON-Serialisierung kann auf dem Server mithilfe der Erweiterungsmethode AddJsonProtocol konfiguriert werden. AddJsonProtocol kann nach AddSignalR in Startup.ConfigureServices hinzugefügt werden. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerOptions-Eigenschaft dieses Objekts ist ein System.Text.Json JsonSerializerOptions-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Dokumentation zu System.Text.Json.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es die Groß- und Kleinschreibung von Eigenschaftsnamen nicht ändert, anstatt die standardmäßigen camelCase-Namen zu verwenden, nutzen Sie den folgenden Code in Program.cs:

builder.Services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

Wechsel zu Newtonsoft.Json

Wenn Sie Features von Newtonsoft.Json benötigen, die in System.Text.Json nicht unterstützt werden, finden Sie weitere Informationen unter Wechsel zu Newtonsoft.Json.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
ClientTimeoutInterval 30 Sekunden Der Server geht davon aus, dass der Client nicht mehr verbunden ist, wenn er in diesem Intervall keine Nachricht (einschließlich Keepalive) erhalten hat. Aufgrund der Art der Implementierung kann es länger als dieses Timeoutintervall dauern, bis der Client als getrennt markiert wird. Der empfohlene Wert ist das Doppelte des KeepAliveInterval-Werts.
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.
StreamBufferCapacity 10 Die maximale Anzahl von Elementen, die für Datenströme von Clientuploads gepuffert werden können. Wenn dieser Grenzwert erreicht ist, wird die Verarbeitung von Aufrufen blockiert, bis der Server Datenstromelemente verarbeitet hat.
MaximumReceiveMessageSize 32 KB Maximale Größe einer einzelnen eingehenden Hubnachricht. Durch das Erhöhen des Werts kann das Risiko von Denial-of-Service-Angriffen (DoS) steigen.
MaximumParallelInvocationsPerClient 1 Die maximale Anzahl von Hubmethoden, die jeder Client parallel aufrufen kann, bevor er in die Warteschlange gestellt wird.
DisableImplicitFromServicesParameters false Die Argumente der Hubmethode werden nach Möglichkeit von DI aufgelöst.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Program.cs bereitgestellt wird.

 builder.Services.AddSignalR(hubOptions =>
 {
     hubOptions.EnableDetailedErrors = true;
     hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
 });

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Program.cs übergeben wird.

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
    options.Transports =
        HttpTransportType.WebSockets |
        HttpTransportType.LongPolling;
}
);
app.Run();

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 64 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
TransportMaxBufferSize 64 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert, bevor er einen Gegendruck feststellt. Wenn Sie diesen Wert erhöhen, kann der Server größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.
MinimumProtocolVersion 0 Geben Sie die Mindestversion des Aushandlungsprotokolls an. Diese wird verwendet, um Clients auf neuere Versionen zu beschränken.
CloseOnAuthenticationExpiration false Legen Sie diese Option fest, um die Nachverfolgung des Authentifizierungsablaufs zu aktivieren, wodurch Verbindungen beendet werden, wenn ein Token abläuft.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Anstelle eines LogLevel-Werts können Sie auch einen string-Wert angeben, der einen Namen für die Protokollstufe darstellt. Dies ist nützlich bei der Konfiguration der SignalR-Protokollierung in Umgebungen, in denen Sie keinen Zugriff auf die LogLevel-Konstanten haben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

In der folgenden Tabelle finden Sie die verfügbaren Protokollstufen. Der Wert, den Sie für configureLogging angeben, legt die minimale Protokollstufe fest, die protokolliert wird. Meldungen, die auf dieser Stufe oder den in der Tabelle aufgeführten Stufen danach protokolliert werden, werden protokolliert.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info oder information LogLevel.Information
warn oder warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

In dieser Version des Java-Clients ist WebSockets der einzige verfügbare Transport.

Im Java-Client wird der Transport mit der Methode withTransport auf der Seite HttpHubConnectionBuilder ausgewählt. Der Java-Client verwendet standardmäßig den WebSockets-Transport.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Hinweis

Der SignalR Java-Client unterstützt noch keinen Transportfallback.

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten:

Option Standardwert Beschreibung
WithServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für Serveraktivitäten und wird direkt auf HubConnectionBuilder festgelegt. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie das Keepalive-Intervall (WithKeepAliveInterval) des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake und ist für das HubConnection-Objekt selbst verfügbar. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
WithKeepAliveInterval 15 Sekunden Bestimmt das Intervall, in dem der Client Ping-Nachrichten sendet und wird direkt auf HubConnectionBuilder festgelegt. Diese Einstellung ermöglicht dem Server, das Erkennen harter Verbindungsabbrüche, z. B. wenn ein Client seinen Computer vom Netzwerk trennt. Wenn Sie eine Nachricht vom Client senden, wird der Timer auf den Beginn des Intervalls zurückgesetzt. Wenn der Client keine Nachricht in dem auf dem Server festgelegten ClientTimeoutInterval gesendet hat, betrachtet der Server den Client als nicht verbunden.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Das folgende Beispiel zeigt Werte, die doppelt so hoch sind wie die Standardwerte:

var builder = new HubConnectionBuilder()
    .WithUrl(Navigation.ToAbsoluteUri("/chathub"))
    .WithServerTimeout(TimeSpan.FromSeconds(60))
    .WithKeepAliveInterval(TimeSpan.FromSeconds(30))
    .Build();

builder.On<string, string>("ReceiveMessage", (user, message) => ...

await builder.StartAsync();

Konfigurieren der zustandsbehafteten Verbindungswiederherstellung

Die zustandsbehaftete SignalR-Wiederherstellung der Verbindung reduziert die wahrgenommene Ausfallzeit von Clients, die eine vorübergehende Unterbrechung in ihrer Netzwerkverbindung aufweisen, z. B. beim Wechsel von Netzwerkverbindungen oder einem kurzen temporären Zugriffsverlust.

Die zustandsbehaftete Wiederherstellung der Verbindung ermöglicht Folgendes:

  • Vorübergehendes Puffern von Daten auf dem Server und Client.
  • Bestätigen von Nachrichten, die sowohl vom Server als auch vom Client empfangen werden (ACK-ing).
  • Es wird erkannt, wenn wieder eine Verbindung besteht, und Nachrichten werden wiedergegeben, die möglicherweise gesendet wurden, während die Verbindung unterbrochen war.

Die zustandsbehaftete Verbindungswiederherstellung ist in ASP.NET Core 8.0 und höher verfügbar.

Melden Sie sich an, um eine zustandsbehaftete erneute Verbindung sowohl am Serverhub-Endpunkt als auch am Client herzustellen:

  • Aktualisieren Sie die Konfiguration des Serverhub-Endpunkts, um die Option AllowStatefulReconnects zu aktivieren:

    app.MapHub<MyHub>("/hubName", options =>
    {
        options.AllowStatefulReconnects = true;
    });
    

    Optional kann die vom Server zulässige maximale Puffergröße in Bytes global oder für einen bestimmten Hub mit der StatefulReconnectBufferSize Option festgelegt werden:

    Die StatefulReconnectBufferSize global festgelegte Option:

    builder.AddSignalR(o => o.StatefulReconnectBufferSize = 1000);
    

    Die StatefulReconnectBufferSize für einen bestimmten Hub festgelegte Option:

    builder.AddSignalR().AddHubOptions<MyHub>(o => o.StatefulReconnectBufferSize = 1000);
    

    Die StatefulReconnectBufferSize Option ist optional mit einer Standardeinstellung von 100.000 Bytes.

  • Aktualisieren Sie den JavaScript- oder TypeScript-Clientcode, um die withStatefulReconnect Option zu aktivieren:

    const builder = new signalR.HubConnectionBuilder()
      .withUrl("/hubname")
      .withStatefulReconnect({ bufferSize: 1000 });  // Optional, defaults to 100,000
    const connection = builder.build();
    

    Die bufferSize Option ist optional mit einer Standardeinstellung von 100.000 Bytes.

  • Aktualisieren Sie den .NET-Clientcode, um die WithStatefulReconnect Option zu aktivieren:

      var builder = new HubConnectionBuilder()
          .WithUrl("<hub url>")
          .WithStatefulReconnect();
      builder.Services.Configure<HubConnectionOptions>(o => o.StatefulReconnectBufferSize = 1000);
      var hubConnection = builder.Build();
    

    Die Option StatefulReconnectBufferSize ist optional. Die Standardeinstellung sind 100.000 Bytes.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.
ApplicationMaxBufferSize 1 MB Die maximale Anzahl der vom Server empfangenen Bytes, die der Client puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Client, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
TransportMaxBufferSize 1 MB Die maximale Anzahl von Bytes, die von der Benutzeranwendung gesendet werden, die der Client vor der Beobachtung eines Gegendrucks puffert. Wenn Sie diesen Wert erhöhen, kann der Client größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        // "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
        headers: { "Foo": "Bar" },
        transport: signalR.HttpTransportType.LongPolling 
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die Serialisierung kann auf dem Server mithilfe der AddJsonProtocol-Erweiterungsmethode konfiguriert werden, die nach AddSignalR in Ihrer Startup.ConfigureServices-Methode hinzugefügt werden kann. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerSettings-Eigenschaft dieses Objekts ist ein Json.NET JsonSerializerSettings-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Json.NET-Dokumentation.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es „PascalCase“-Eigenschaftsnamen anstelle der camelCase-Standardnamen verwendet, verwenden Sie den folgenden Code in Startup.ConfigureServices:

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Startup.ConfigureServices bereitgestellt wird.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Startup.Configure übergeben wird.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSignalR((configure) =>
    {
        var desiredTransports =
            HttpTransportType.WebSockets |
            HttpTransportType.LongPolling;

        configure.MapHub<ChatHub>("/chathub", (options) =>
        {
            options.Transports = desiredTransports;
        });
    });
}

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 32 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten zu empfangen, kann sich jedoch negativ auf den Arbeitsspeicherverbrauch auswirken.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
TransportMaxBufferSize 32 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten zu senden, kann sich jedoch negativ auf den Arbeitsspeicherverbrauch auswirken.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten sind für das HubConnection-Objekt selbst verfügbar:

Option Standardwert Beschreibung
ServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für die Serveraktivität. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie der KeepAliveInterval-Wert des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die Serialisierung kann auf dem Server mithilfe der AddJsonProtocol-Erweiterungsmethode konfiguriert werden, die nach AddSignalR in Ihrer Startup.ConfigureServices-Methode hinzugefügt werden kann. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerSettings-Eigenschaft dieses Objekts ist ein Json.NET JsonSerializerSettings-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Json.NET-Dokumentation.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es „PascalCase“-Eigenschaftsnamen anstelle der camelCase-Standardnamen verwendet, verwenden Sie den folgenden Code in Startup.ConfigureServices:

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerSettings.ContractResolver =
            new DefaultContractResolver();
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
ClientTimeoutInterval 30 Sekunden Der Server geht davon aus, dass der Client nicht mehr verbunden ist, wenn er in diesem Intervall keine Nachricht (einschließlich Keepalive) erhalten hat. Aufgrund der Art der Implementierung kann es länger als dieses Timeoutintervall dauern, bis der Client als getrennt markiert wird. Der empfohlene Wert ist das Doppelte des KeepAliveInterval-Werts.
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Startup.ConfigureServices bereitgestellt wird.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Startup.Configure übergeben wird.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseSignalR((configure) =>
    {
        var desiredTransports =
            HttpTransportType.WebSockets |
            HttpTransportType.LongPolling;

        configure.MapHub<ChatHub>("/chathub", (options) =>
        {
            options.Transports = desiredTransports;
        });
    });
}

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 32 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten zu empfangen, kann sich jedoch negativ auf den Arbeitsspeicherverbrauch auswirken.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
TransportMaxBufferSize 32 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten zu senden, kann sich jedoch negativ auf den Arbeitsspeicherverbrauch auswirken.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

In dieser Version des Java-Clients ist WebSockets der einzige verfügbare Transport.

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten sind für das HubConnection-Objekt selbst verfügbar:

Option Standardwert Beschreibung
ServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für die Serveraktivität. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie der KeepAliveInterval-Wert des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Legt das Intervall fest, in dem der Client Ping-Nachrichten sendet. Wenn Sie eine Nachricht vom Client senden, wird der Timer auf den Beginn des Intervalls zurückgesetzt. Wenn der Client keine Nachricht in dem auf dem Server festgelegten ClientTimeoutInterval gesendet hat, betrachtet der Server den Client als nicht verbunden.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die JSON-Serialisierung kann auf dem Server mithilfe der Erweiterungsmethode AddJsonProtocol konfiguriert werden. AddJsonProtocol kann nach AddSignalR in Startup.ConfigureServices hinzugefügt werden. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerOptions-Eigenschaft dieses Objekts ist ein System.Text.Json JsonSerializerOptions-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Dokumentation zu System.Text.Json.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es die Groß- und Kleinschreibung von Eigenschaftsnamen nicht ändert, anstatt die standardmäßigen camelCase-Namen zu verwenden, nutzen Sie den folgenden Code in Startup.ConfigureServices:

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

Wechsel zu Newtonsoft.Json

Wenn Sie Features von Newtonsoft.Json benötigen, die in System.Text.Json nicht unterstützt werden, finden Sie weitere Informationen unter Wechsel zu Newtonsoft.Json.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
ClientTimeoutInterval 30 Sekunden Der Server geht davon aus, dass der Client nicht mehr verbunden ist, wenn er in diesem Intervall keine Nachricht (einschließlich Keepalive) erhalten hat. Aufgrund der Art der Implementierung kann es länger als dieses Timeoutintervall dauern, bis der Client als getrennt markiert wird. Der empfohlene Wert ist das Doppelte des KeepAliveInterval-Werts.
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.
StreamBufferCapacity 10 Die maximale Anzahl von Elementen, die für Datenströme von Clientuploads gepuffert werden können. Wenn dieser Grenzwert erreicht ist, wird die Verarbeitung von Aufrufen blockiert, bis der Server Datenstromelemente verarbeitet hat.
MaximumReceiveMessageSize 32 KB Maximale Größe einer einzelnen eingehenden Hubnachricht. Das Erhöhen des Werts kann das Risiko von Denial-of-Service-Angriffen (DoS) erhöhen.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Startup.ConfigureServices bereitgestellt wird.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Startup.Configure übergeben wird.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chathub", options =>
        {
            options.Transports =
                HttpTransportType.WebSockets |
                HttpTransportType.LongPolling;
        });
    });
}

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 32 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
TransportMaxBufferSize 32 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert, bevor er einen Gegendruck feststellt. Wenn Sie diesen Wert erhöhen, kann der Server größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Anstelle eines LogLevel-Werts können Sie auch einen string-Wert angeben, der einen Namen für die Protokollstufe darstellt. Dies ist nützlich bei der Konfiguration der SignalR-Protokollierung in Umgebungen, in denen Sie keinen Zugriff auf die LogLevel-Konstanten haben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

In der folgenden Tabelle finden Sie die verfügbaren Protokollstufen. Der Wert, den Sie für configureLogging angeben, legt die minimale Protokollstufe fest, die protokolliert wird. Meldungen, die auf dieser Stufe oder den in der Tabelle aufgeführten Stufen danach protokolliert werden, werden protokolliert.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info oder information LogLevel.Information
warn oder warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

In dieser Version des Java-Clients ist WebSockets der einzige verfügbare Transport.

Im Java-Client wird der Transport mit der Methode withTransport auf der Seite HttpHubConnectionBuilder ausgewählt. Der Java-Client verwendet standardmäßig den WebSockets-Transport.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Hinweis

Der SignalR Java-Client unterstützt noch keinen Transportfallback.

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten sind für das HubConnection-Objekt selbst verfügbar:

Option Standardwert Beschreibung
ServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für die Serveraktivität. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie der KeepAliveInterval-Wert des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Legt das Intervall fest, in dem der Client Ping-Nachrichten sendet. Wenn Sie eine Nachricht vom Client senden, wird der Timer auf den Beginn des Intervalls zurückgesetzt. Wenn der Client keine Nachricht in dem auf dem Server festgelegten ClientTimeoutInterval gesendet hat, betrachtet der Server den Client als nicht verbunden.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die JSON-Serialisierung kann auf dem Server mithilfe der Erweiterungsmethode AddJsonProtocol konfiguriert werden. AddJsonProtocol kann nach AddSignalR in Startup.ConfigureServices hinzugefügt werden. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerOptions-Eigenschaft dieses Objekts ist ein System.Text.Json JsonSerializerOptions-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Dokumentation zu System.Text.Json.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es die Groß- und Kleinschreibung von Eigenschaftsnamen nicht ändert, anstatt die standardmäßigen camelCase-Namen zu verwenden, nutzen Sie den folgenden Code in Startup.ConfigureServices:

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

Wechsel zu Newtonsoft.Json

Wenn Sie Features von Newtonsoft.Json benötigen, die in System.Text.Json nicht unterstützt werden, finden Sie weitere Informationen unter Wechsel zu Newtonsoft.Json.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
ClientTimeoutInterval 30 Sekunden Der Server geht davon aus, dass der Client nicht mehr verbunden ist, wenn er in diesem Intervall keine Nachricht (einschließlich Keepalive) erhalten hat. Aufgrund der Art der Implementierung kann es länger als dieses Timeoutintervall dauern, bis der Client als getrennt markiert wird. Der empfohlene Wert ist das Doppelte des KeepAliveInterval-Werts.
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.
StreamBufferCapacity 10 Die maximale Anzahl von Elementen, die für Datenströme von Clientuploads gepuffert werden können. Wenn dieser Grenzwert erreicht ist, wird die Verarbeitung von Aufrufen blockiert, bis der Server Datenstromelemente verarbeitet hat.
MaximumReceiveMessageSize 32 KB Maximale Größe einer einzelnen eingehenden Hubnachricht. Das Erhöhen des Werts kann das Risiko von Denial-of-Service-Angriffen (DoS) erhöhen.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Startup.ConfigureServices bereitgestellt wird.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Startup.Configure übergeben wird.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chathub", options =>
        {
            options.Transports =
                HttpTransportType.WebSockets |
                HttpTransportType.LongPolling;
        });
    });
}

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 32 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
TransportMaxBufferSize 32 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert, bevor er einen Gegendruck feststellt. Wenn Sie diesen Wert erhöhen, kann der Server größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.
MinimumProtocolVersion 0 Geben Sie die Mindestversion des Aushandlungsprotokolls an. Diese wird verwendet, um Clients auf neuere Versionen zu beschränken.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Anstelle eines LogLevel-Werts können Sie auch einen string-Wert angeben, der einen Namen für die Protokollstufe darstellt. Dies ist nützlich bei der Konfiguration der SignalR-Protokollierung in Umgebungen, in denen Sie keinen Zugriff auf die LogLevel-Konstanten haben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

In der folgenden Tabelle finden Sie die verfügbaren Protokollstufen. Der Wert, den Sie für configureLogging angeben, legt die minimale Protokollstufe fest, die protokolliert wird. Meldungen, die auf dieser Stufe oder den in der Tabelle aufgeführten Stufen danach protokolliert werden, werden protokolliert.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info oder information LogLevel.Information
warn oder warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

In dieser Version des Java-Clients ist WebSockets der einzige verfügbare Transport.

Im Java-Client wird der Transport mit der Methode withTransport auf der Seite HttpHubConnectionBuilder ausgewählt. Der Java-Client verwendet standardmäßig den WebSockets-Transport.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Hinweis

Der SignalR Java-Client unterstützt noch keinen Transportfallback.

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten sind für das HubConnection-Objekt selbst verfügbar:

Option Standardwert Beschreibung
ServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für die Serveraktivität. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie der KeepAliveInterval-Wert des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Legt das Intervall fest, in dem der Client Ping-Nachrichten sendet. Wenn Sie eine Nachricht vom Client senden, wird der Timer auf den Beginn des Intervalls zurückgesetzt. Wenn der Client keine Nachricht in dem auf dem Server festgelegten ClientTimeoutInterval gesendet hat, betrachtet der Server den Client als nicht verbunden.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        skipNegotiation: true,
        transport: signalR.HttpTransportType.WebSockets
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die JSON-Serialisierung kann auf dem Server mithilfe der Erweiterungsmethode AddJsonProtocol konfiguriert werden. AddJsonProtocol kann nach AddSignalR in Startup.ConfigureServices hinzugefügt werden. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerOptions-Eigenschaft dieses Objekts ist ein System.Text.Json JsonSerializerOptions-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Dokumentation zu System.Text.Json.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es die Groß- und Kleinschreibung von Eigenschaftsnamen nicht ändert, anstatt die standardmäßigen camelCase-Namen zu verwenden, nutzen Sie den folgenden Code in Startup.ConfigureServices:

services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

Wechsel zu Newtonsoft.Json

Wenn Sie Features von Newtonsoft.Json benötigen, die in System.Text.Json nicht unterstützt werden, finden Sie weitere Informationen unter Wechsel zu Newtonsoft.Json.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
ClientTimeoutInterval 30 Sekunden Der Server geht davon aus, dass der Client nicht mehr verbunden ist, wenn er in diesem Intervall keine Nachricht (einschließlich Keepalive) erhalten hat. Aufgrund der Art der Implementierung kann es länger als dieses Timeoutintervall dauern, bis der Client als getrennt markiert wird. Der empfohlene Wert ist das Doppelte des KeepAliveInterval-Werts.
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.
StreamBufferCapacity 10 Die maximale Anzahl von Elementen, die für Datenströme von Clientuploads gepuffert werden können. Wenn dieser Grenzwert erreicht ist, wird die Verarbeitung von Aufrufen blockiert, bis der Server Datenstromelemente verarbeitet hat.
MaximumReceiveMessageSize 32 KB Maximale Größe einer einzelnen eingehenden Hubnachricht. Das Erhöhen des Werts kann das Risiko von Denial-of-Service-Angriffen (DoS) erhöhen.
MaximumParallelInvocationsPerClient 1 Die maximale Anzahl von Hubmethoden, die jeder Client parallel aufrufen kann, bevor er in die Warteschlange gestellt wird.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Startup.ConfigureServices bereitgestellt wird.

public void ConfigureServices(IServiceCollection services)
{
    services.AddSignalR(hubOptions =>
    {
        hubOptions.EnableDetailedErrors = true;
        hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
    });
}

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Startup.Configure übergeben wird.

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseRouting();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapHub<ChatHub>("/chathub", options =>
        {
            options.Transports =
                HttpTransportType.WebSockets |
                HttpTransportType.LongPolling;
        });
    });
}

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 32 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
TransportMaxBufferSize 32 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert, bevor er einen Gegendruck feststellt. Wenn Sie diesen Wert erhöhen, kann der Server größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.
MinimumProtocolVersion 0 Geben Sie die Mindestversion des Aushandlungsprotokolls an. Diese wird verwendet, um Clients auf neuere Versionen zu beschränken.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Anstelle eines LogLevel-Werts können Sie auch einen string-Wert angeben, der einen Namen für die Protokollstufe darstellt. Dies ist nützlich bei der Konfiguration der SignalR-Protokollierung in Umgebungen, in denen Sie keinen Zugriff auf die LogLevel-Konstanten haben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

In der folgenden Tabelle finden Sie die verfügbaren Protokollstufen. Der Wert, den Sie für configureLogging angeben, legt die minimale Protokollstufe fest, die protokolliert wird. Meldungen, die auf dieser Stufe oder den in der Tabelle aufgeführten Stufen danach protokolliert werden, werden protokolliert.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info oder information LogLevel.Information
warn oder warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

In dieser Version des Java-Clients ist WebSockets der einzige verfügbare Transport.

Im Java-Client wird der Transport mit der Methode withTransport auf der Seite HttpHubConnectionBuilder ausgewählt. Der Java-Client verwendet standardmäßig den WebSockets-Transport.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Hinweis

Der SignalR Java-Client unterstützt noch keinen Transportfallback.

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten sind für das HubConnection-Objekt selbst verfügbar:

Option Standardwert Beschreibung
ServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für die Serveraktivität. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie der KeepAliveInterval-Wert des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Legt das Intervall fest, in dem der Client Ping-Nachrichten sendet. Wenn Sie eine Nachricht vom Client senden, wird der Timer auf den Beginn des Intervalls zurückgesetzt. Wenn der Client keine Nachricht in dem auf dem Server festgelegten ClientTimeoutInterval gesendet hat, betrachtet der Server den Client als nicht verbunden.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        // "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
        headers: { "Foo": "Bar" },
        transport: signalR.HttpTransportType.LongPolling 
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die JSON-Serialisierung kann auf dem Server mithilfe der Erweiterungsmethode AddJsonProtocol konfiguriert werden. AddJsonProtocol kann nach AddSignalR in Program.cs hinzugefügt werden. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerOptions-Eigenschaft dieses Objekts ist ein System.Text.Json JsonSerializerOptions-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Dokumentation zu System.Text.Json.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es die Groß- und Kleinschreibung von Eigenschaftsnamen nicht ändert, anstatt die standardmäßigen camelCase-Namen zu verwenden, nutzen Sie den folgenden Code in Program.cs:

builder.Services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

Wechsel zu Newtonsoft.Json

Wenn Sie Features von Newtonsoft.Json benötigen, die in System.Text.Json nicht unterstützt werden, finden Sie weitere Informationen unter Wechsel zu Newtonsoft.Json.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
ClientTimeoutInterval 30 Sekunden Der Server geht davon aus, dass der Client nicht mehr verbunden ist, wenn er in diesem Intervall keine Nachricht (einschließlich Keepalive) erhalten hat. Aufgrund der Art der Implementierung kann es länger als dieses Timeoutintervall dauern, bis der Client als getrennt markiert wird. Der empfohlene Wert ist das Doppelte des KeepAliveInterval-Werts.
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.
StreamBufferCapacity 10 Die maximale Anzahl von Elementen, die für Datenströme von Clientuploads gepuffert werden können. Wenn dieser Grenzwert erreicht ist, wird die Verarbeitung von Aufrufen blockiert, bis der Server Datenstromelemente verarbeitet hat.
MaximumReceiveMessageSize 32 KB Maximale Größe einer einzelnen eingehenden Hubnachricht. Das Erhöhen des Werts kann das Risiko von Denial-of-Service-Angriffen (DoS) erhöhen.
MaximumParallelInvocationsPerClient 1 Die maximale Anzahl von Hubmethoden, die jeder Client parallel aufrufen kann, bevor er in die Warteschlange gestellt wird.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Program.cs bereitgestellt wird.

builder.Services.AddSignalR(hubOptions =>
{
    hubOptions.EnableDetailedErrors = true;
    hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
});

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Program.cs übergeben wird.

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
    options.Transports =
        HttpTransportType.WebSockets |
        HttpTransportType.LongPolling;
}
);
app.Run();

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 64 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
TransportMaxBufferSize 64 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert, bevor er einen Gegendruck feststellt. Wenn Sie diesen Wert erhöhen, kann der Server größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.
MinimumProtocolVersion 0 Geben Sie die Mindestversion des Aushandlungsprotokolls an. Diese wird verwendet, um Clients auf neuere Versionen zu beschränken.
CloseOnAuthenticationExpiration false Legen Sie diese Option fest, um die Nachverfolgung des Authentifizierungsablaufs zu aktivieren, wodurch Verbindungen geschlossen werden, wenn ein Token abläuft.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Anstelle eines LogLevel-Werts können Sie auch einen string-Wert angeben, der einen Namen für die Protokollstufe darstellt. Dies ist nützlich bei der Konfiguration der SignalR-Protokollierung in Umgebungen, in denen Sie keinen Zugriff auf die LogLevel-Konstanten haben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

In der folgenden Tabelle finden Sie die verfügbaren Protokollstufen. Der Wert, den Sie für configureLogging angeben, legt die minimale Protokollstufe fest, die protokolliert wird. Meldungen, die auf dieser Stufe oder den in der Tabelle aufgeführten Stufen danach protokolliert werden, werden protokolliert.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info oder information LogLevel.Information
warn oder warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

In dieser Version des Java-Clients ist WebSockets der einzige verfügbare Transport.

Im Java-Client wird der Transport mit der Methode withTransport auf der Seite HttpHubConnectionBuilder ausgewählt. Der Java-Client verwendet standardmäßig den WebSockets-Transport.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Hinweis

Der SignalR Java-Client unterstützt noch keinen Transportfallback.

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten sind für das HubConnection-Objekt selbst verfügbar:

Option Standardwert Beschreibung
ServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für die Serveraktivität. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie der KeepAliveInterval-Wert des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Legt das Intervall fest, in dem der Client Ping-Nachrichten sendet. Wenn Sie eine Nachricht vom Client senden, wird der Timer auf den Beginn des Intervalls zurückgesetzt. Wenn der Client keine Nachricht in dem auf dem Server festgelegten ClientTimeoutInterval gesendet hat, betrachtet der Server den Client als nicht verbunden.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.
ApplicationMaxBufferSize 1 MB Die maximale Anzahl der vom Server empfangenen Bytes, die der Client puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Client, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
TransportMaxBufferSize 1 MB Die maximale Anzahl von Bytes, die von der Benutzeranwendung gesendet werden, die der Client vor der Beobachtung eines Gegendrucks puffert. Wenn Sie diesen Wert erhöhen, kann der Client größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        // "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
        headers: { "Foo": "Bar" },
        transport: signalR.HttpTransportType.LongPolling 
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen

JSON/MessagePack-Serialisierungsoptionen

ASP.NET Core SignalR unterstützt zwei Protokolle für die Codierung von Nachrichten: JSON und MessagePack. Jedes Protokoll verfügt über Konfigurationsoptionen für die Serialisierung.

Die JSON-Serialisierung kann auf dem Server mithilfe der Erweiterungsmethode AddJsonProtocol konfiguriert werden. AddJsonProtocol kann nach AddSignalR in Startup.ConfigureServices hinzugefügt werden. Die Methode AddJsonProtocol übernimmt einen Delegaten, der ein options-Objekt empfängt. Die PayloadSerializerOptions-Eigenschaft dieses Objekts ist ein System.Text.Json JsonSerializerOptions-Objekt, das zur Konfiguration der Serialisierung von Argumenten und Rückgabewerten verwendet werden kann. Weitere Informationen finden Sie in der Dokumentation zu System.Text.Json.

Um z. B. das Serialisierungsmodul so zu konfigurieren, dass es die Groß- und Kleinschreibung von Eigenschaftsnamen nicht ändert, anstatt die standardmäßigen camelCase-Namen zu verwenden, nutzen Sie den folgenden Code in Program.cs:

builder.Services.AddSignalR()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    });

Im .NET-Client existiert die gleiche AddJsonProtocol-Erweiterungsmethode für HubConnectionBuilder. Der Namespace Microsoft.Extensions.DependencyInjection muss importiert werden, um die Erweiterungsmethode aufzulösen:

// At the top of the file:
using Microsoft.Extensions.DependencyInjection;

// When constructing your connection:
var connection = new HubConnectionBuilder()
    .AddJsonProtocol(options => {
        options.PayloadSerializerOptions.PropertyNamingPolicy = null;
    })
    .Build();

Hinweis

Es ist derzeit nicht möglich, die JSON-Serialisierung im JavaScript-Client zu konfigurieren.

Wechsel zu Newtonsoft.Json

Wenn Sie Features von Newtonsoft.Json benötigen, die in System.Text.Json nicht unterstützt werden, finden Sie weitere Informationen unter Wechsel zu Newtonsoft.Json.

MessagePack-Serialisierungsoptionen

Die MessagePack-Serialisierung kann konfiguriert werden, indem ein Delegat für den AddMessagePackProtocol-Aufruf bereitgestellt wird. Weitere Informationen finden Sie unter MessagePack in SignalR.

Hinweis

Es ist derzeit nicht möglich, die MessagePack-Serialisierung im JavaScript-Client zu konfigurieren.

Konfigurieren von Serveroptionen

In der folgenden Tabelle werden die Optionen für die Konfiguration von SignalR-Hubs beschrieben:

Option Standardwert Beschreibung
ClientTimeoutInterval 30 Sekunden Der Server geht davon aus, dass der Client nicht mehr verbunden ist, wenn er in diesem Intervall keine Nachricht (einschließlich Keepalive) erhalten hat. Aufgrund der Art der Implementierung kann es länger als dieses Timeoutintervall dauern, bis der Client als getrennt markiert wird. Der empfohlene Wert ist das Doppelte des KeepAliveInterval-Werts.
HandshakeTimeout 15 Sekunden Wenn der Client innerhalb dieses Zeitintervalls keine erste Handshakenachricht sendet, wird die Verbindung geschlossen. Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Wenn der Server innerhalb dieses Intervalls keine Nachricht gesendet hat, wird automatisch eine Ping-Nachricht gesendet, um die Verbindung offen zu halten. Wenn Sie KeepAliveInterval ändern, ändern Sie die ServerTimeout- oder serverTimeoutInMilliseconds-Einstellung auf dem Client. Der empfohlene ServerTimeout- oder serverTimeoutInMilliseconds-Wert ist das Doppelte des KeepAliveInterval Werts.
SupportedProtocols Alle installierten Protokolle Von diesem Hub unterstützte Protokolle Standardmäßig sind alle auf dem Server registrierten Protokolle erlaubt. Protokolle können aus dieser Liste entfernt werden, um bestimmte Protokolle für einzelne Hubs zu deaktivieren.
EnableDetailedErrors false Bei true werden detaillierte Ausnahmemeldungen an Clients zurückgegeben, wenn eine Ausnahme in einer Hubmethode ausgelöst wird. Der Standardwert ist false, da diese Ausnahmemeldungen vertrauliche Informationen enthalten können.
StreamBufferCapacity 10 Die maximale Anzahl von Elementen, die für Datenströme von Clientuploads gepuffert werden können. Wenn dieser Grenzwert erreicht ist, wird die Verarbeitung von Aufrufen blockiert, bis der Server Datenstromelemente verarbeitet hat.
MaximumReceiveMessageSize 32 KB Maximale Größe einer einzelnen eingehenden Hubnachricht. Das Erhöhen des Werts kann das Risiko von Denial-of-Service-Angriffen (DoS) erhöhen.
MaximumParallelInvocationsPerClient 1 Die maximale Anzahl von Hubmethoden, die jeder Client parallel aufrufen kann, bevor er in die Warteschlange gestellt wird.
DisableImplicitFromServicesParameters false Die Argumente der Hubmethode werden nach Möglichkeit von DI aufgelöst.

Optionen können für alle Hubs konfiguriert werden, indem ein Optionsdelegat für den AddSignalR-Aufruf in Program.cs bereitgestellt wird.

 builder.Services.AddSignalR(hubOptions =>
 {
     hubOptions.EnableDetailedErrors = true;
     hubOptions.KeepAliveInterval = TimeSpan.FromMinutes(1);
 });

Optionen für einen einzelnen Hub haben Vorrang vor den globalen Optionen in AddSignalR und können mit AddHubOptions konfiguriert werden:

builder.Services.AddSignalR().AddHubOptions<ChatHub>(options =>
{
    options.EnableDetailedErrors = true;
});

Erweiterte HTTP-Konfigurationsoptionen

Verwenden Sie HttpConnectionDispatcherOptions, um erweiterte Einstellungen in Bezug auf Datentransporte und Speicherpufferverwaltung festzulegen. Diese Optionen werden konfiguriert, indem ein Delegat an MapHub in Program.cs übergeben wird.

using Microsoft.AspNetCore.Http.Connections;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddRazorPages();
builder.Services.AddSignalR();

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();

app.UseAuthorization();

app.MapRazorPages();
app.MapHub<ChatHub>("/chathub", options =>
{
    options.Transports =
        HttpTransportType.WebSockets |
        HttpTransportType.LongPolling;
}
);
app.Run();

In der folgenden Tabelle werden die Optionen für die Konfiguration der erweiterten HTTP-Optionen von ASP.NET Core SignalR beschrieben:

Option Standardwert Beschreibung
ApplicationMaxBufferSize 64 KB Die maximale Anzahl der vom Client empfangenen Bytes, die der Server puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Server, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
TransportMaxBufferSize 64 KB Die maximale Anzahl der von der App gesendeten Bytes, die der Server puffert, bevor er einen Gegendruck feststellt. Wenn Sie diesen Wert erhöhen, kann der Server größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.
AuthorizationData Automatisch erfasste Daten aus den Authorize-Attributen, die auf die Hubklasse angewendet werden. Eine Liste von IAuthorizeData-Objekten, die verwendet wird, um festzustellen, ob ein Client berechtigt ist, eine Verbindung mit dem Hub herzustellen.
Transports Alle Transporte sind aktiviert. Eine Bitflags-Enumeration mit HttpTransportType-Werten, die die Transporte einschränken kann, die ein Client für die Verbindung verwenden kann.
LongPolling Siehe unten. Zusätzliche Optionen, die speziell für den Transport langer Abrufe gelten.
WebSockets Siehe unten. Zusätzliche Optionen speziell für den WebSockets-Transport.
MinimumProtocolVersion 0 Geben Sie die Mindestversion des Aushandlungsprotokolls an. Diese wird verwendet, um Clients auf neuere Versionen zu beschränken.
CloseOnAuthenticationExpiration false Legen Sie diese Option fest, um die Nachverfolgung des Authentifizierungsablaufs zu aktivieren, wodurch Verbindungen geschlossen werden, wenn ein Token abläuft.

Der Transport langer Abrufe verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft LongPolling konfiguriert werden können:

Option Standardwert Beschreibung
PollTimeout 90 Sekunden Die maximale Zeitspanne, die der Server auf eine Nachricht an den Client wartet, bevor er eine einzelne Abrufanforderung beendet. Eine Verringerung dieses Werts veranlasst den Client, häufiger neue Abrufanforderungen zu stellen.

Der WebSocket-Transport verfügt über zusätzliche Optionen, die mithilfe der Eigenschaft WebSockets konfiguriert werden können:

Option Standardwert Beschreibung
CloseTimeout 5 Sekunden Wenn der Client nach dem Schließen des Servers innerhalb dieses Zeitintervalls nicht geschlossen werden kann, wird die Verbindung beendet.
SubProtocolSelector null Ein Delegat, der verwendet werden kann, um den Sec-WebSocket-Protocol-Header auf einen benutzerdefinierten Wert festzulegen. Der Delegat erhält die vom Client angeforderten Werte als Eingabe und soll den gewünschten Wert zurückgeben.

Konfigurieren von Clientoptionen

Clientoptionen können für den Typ HubConnectionBuilder konfiguriert werden (verfügbar in den .NET- und JavaScript-Clients). Er ist auch im Java-Client verfügbar, aber die Unterklasse HttpHubConnectionBuilder enthält die Konfigurationsoptionen für den Builder, ebenso wie die HubConnection selbst.

Konfigurieren der Protokollierung

Die Protokollierung wird im .NET-Client mithilfe der Methode ConfigureLogging konfiguriert. Anbieter und Filter für die Protokollierung können auf die gleiche Weise registriert werden wie auf dem Server. Weitere Informationen finden Sie in der Dokumentation zum Protokollieren in ASP.NET Core.

Hinweis

Zum Registrieren von Protokollierungsanbietern müssen Sie die erforderlichen Pakete installieren. Eine vollständige Liste finden Sie im Abschnitt Integrierte Protokollierungsanbieter in den Dokumentationen.

Um z. B. die Konsolenprotokollierung zu aktivieren, installieren Sie das Microsoft.Extensions.Logging.Console-NuGet-Paket. Rufen Sie die AddConsole-Erweiterungsmethode auf:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub")
    .ConfigureLogging(logging => {
        logging.SetMinimumLevel(LogLevel.Information);
        logging.AddConsole();
    })
    .Build();

Im JavaScript-Client gibt es eine ähnliche configureLogging-Methode. Geben Sie einen LogLevel-Wert an, der die Mindeststufe der zu erzeugenden Protokollmeldungen angibt. Die Protokolle werden in das Konsolenfenster des Browsers geschrieben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging(signalR.LogLevel.Information)
    .build();

Anstelle eines LogLevel-Werts können Sie auch einen string-Wert angeben, der einen Namen für die Protokollstufe darstellt. Dies ist nützlich bei der Konfiguration der SignalR-Protokollierung in Umgebungen, in denen Sie keinen Zugriff auf die LogLevel-Konstanten haben.

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub")
    .configureLogging("warn")
    .build();

In der folgenden Tabelle finden Sie die verfügbaren Protokollstufen. Der Wert, den Sie für configureLogging angeben, legt die minimale Protokollstufe fest, die protokolliert wird. Meldungen, die auf dieser Stufe oder den in der Tabelle aufgeführten Stufen danach protokolliert werden, werden protokolliert.

String LogLevel
trace LogLevel.Trace
debug LogLevel.Debug
info oder information LogLevel.Information
warn oder warning LogLevel.Warning
error LogLevel.Error
critical LogLevel.Critical
none LogLevel.None

Hinweis

Um die Protokollierung vollständig zu deaktivieren, geben Sie signalR.LogLevel.None in der configureLogging-Methode an.

Weitere Informationen zur Protokollierung finden Sie unter SignalR-Diagnose: Dokumentation.

Der SignalR Java-Client verwendet die SLF4J-Bibliothek für die Protokollierung. Es handelt sich um eine allgemeine Protokollierungs-API, mit der Benutzer der Bibliothek ihre eigene spezifische Protokollierungsimplementierung wählen können, indem sie eine bestimmte Protokollierungsabhängigkeit einbinden. Der folgende Codeschnipsel zeigt die Verwendung von java.util.logging mit dem SignalR-Java-Client.

implementation 'org.slf4j:slf4j-jdk14:1.7.25'

Wenn Sie die Protokollierung in Ihren Abhängigkeiten nicht konfigurieren, lädt SLF4J eine standardmäßige nicht vorgangsspezifische Protokollierung mit der folgenden Warnmeldung:

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

Diese kann gefahrlos ignoriert werden.

Konfigurieren zulässiger Transporte

Die von SignalR verwendeten Transporte können mit dem WithUrl-Aufruf (withUrl in JavaScript) konfiguriert werden. Ein bitweises ODER der Werte von HttpTransportType kann verwendet werden, um den Client darauf zu beschränken, nur die angegebenen Transporte zu verwenden. Alle Transporte sind standardmäßig aktiviert.

Wenn Sie z. B. den Transport der vom Server gesendeten Ereignisse deaktivieren, aber WebSockets-Verbindungen und Verbindungen für lange Abrufe zulassen möchten:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", HttpTransportType.WebSockets | HttpTransportType.LongPolling)
    .Build();

Im JavaScript-Client werden die Transporte konfiguriert, indem Sie das Feld transport für das bereitgestellte Optionsobjekt auf withUrl festlegen:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", { transport: signalR.HttpTransportType.WebSockets | signalR.HttpTransportType.LongPolling })
    .build();

In dieser Version des Java-Clients ist WebSockets der einzige verfügbare Transport.

Im Java-Client wird der Transport mit der Methode withTransport auf der Seite HttpHubConnectionBuilder ausgewählt. Der Java-Client verwendet standardmäßig den WebSockets-Transport.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withTransport(TransportEnum.WEBSOCKETS)
    .build();

Hinweis

Der SignalR Java-Client unterstützt noch keinen Transportfallback.

Konfigurieren der Bearerauthentifizierung

Um Authentifizierungsdaten zusammen mit SignalR-Anforderungen bereitzustellen, verwenden Sie die Option AccessTokenProvider (accessTokenFactory in JavaScript), um eine Funktion anzugeben, die das gewünschte Zugriffstoken zurückgibt. Im .NET-Client wird dieses Zugriffstoken als HTTP-Token für die „Bearerauthentifizierung“ übergeben (mithilfe des Authorization-Headers mit einem Typ von Bearer). Im JavaScript-Client wird das Zugriffstoken als Bearertoken verwendet, außer in einigen wenigen Fällen, in denen die Browser-APIs die Möglichkeit zur Anwendung von Headern einschränken (insbesondere in vom Server gesendeten Ereignissen und WebSockets-Anforderungen). In diesen Fällen wird das Zugriffstoken als Abfragezeichenfolgenwert access_token bereitgestellt.

Im .NET-Client kann die Option AccessTokenProvider mithilfe des Optionsdelegaten in WithUrl angegeben werden:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.AccessTokenProvider = async () => {
            // Get and return the access token.
        };
    })
    .Build();

Im JavaScript-Client wird das Zugriffstoken konfiguriert, indem das Feld accessTokenFactory für das Optionsobjekt in withUrl festgelegt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        accessTokenFactory: () => {
            // Get and return the access token.
            // This function can return a JavaScript Promise if asynchronous
            // logic is required to retrieve the access token.
        }
    })
    .build();

In dem SignalR Java-Client können Sie ein Bearertoken konfigurieren, das Sie zur Authentifizierung verwenden, indem Sie dem HttpHubConnectionBuilder eine Zugriffstokenfactory zur Verfügung stellen. Verwenden Sie withAccessTokenFactory, um eine RxJava Single<String> bereitzustellen. Mit einem Aufruf von Single.defer können Sie Logik schreiben, um Zugriffstoken für Ihren Client zu erstellen.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
    .withAccessTokenProvider(Single.defer(() -> {
        // Your logic here.
        return Single.just("An Access Token");
    })).build();

Konfigurieren von Timeout- und Keepalive-Optionen

Zusätzliche Optionen für die Konfiguration von Timeout- und Keepalive-Verhalten sind für das HubConnection-Objekt selbst verfügbar:

Option Standardwert Beschreibung
ServerTimeout 30 Sekunden (30.000 Millisekunden) Timeout für die Serveraktivität. Wenn der Server in diesem Intervall keine Nachricht gesendet hat, betrachtet der Client den Server als nicht verbunden und löst das Ereignis Closed (onclose in JavaScript) aus. Dieser Wert muss groß genug sein, damit eine Ping-Nachricht vom Server gesendet und vom Client innerhalb des Timeoutintervalls empfangen werden kann. Empfohlen wird eine Zahl, die mindestens doppelt so hoch ist wie der KeepAliveInterval-Wert des Servers, um Zeit für das Eintreffen von Pings zu haben.
HandshakeTimeout 15 Sekunden Timeout für den anfänglichen Serverhandshake. Wenn der Server in diesem Intervall keine Handshakeantwort sendet, bricht der Client den Handshake ab und löst das Ereignis Closed aus (onclose in JavaScript). Dies ist eine erweiterte Einstellung, die nur geändert werden sollte, wenn aufgrund einer schwerwiegenden Netzwerklatenz entsprechende Timeoutfehler beim Handshake auftreten. Weitere Informationen zum Handshakeprozess finden Sie in der SignalR-Hubprotokollspezifikation.
KeepAliveInterval 15 Sekunden Legt das Intervall fest, in dem der Client Ping-Nachrichten sendet. Wenn Sie eine Nachricht vom Client senden, wird der Timer auf den Beginn des Intervalls zurückgesetzt. Wenn der Client keine Nachricht in dem auf dem Server festgelegten ClientTimeoutInterval gesendet hat, betrachtet der Server den Client als nicht verbunden.

Im .NET-Client werden die Timeoutwerte als TimeSpan-Werte angegeben.

Zusätzliche Optionen konfigurieren

Zusätzliche Optionen können in der WithUrl-Methode (withUrl in JavaScript) auf HubConnectionBuilder oder über die verschiedenen Konfigurations-APIs auf dem HttpHubConnectionBuilder im Java-Client konfiguriert werden:

.NET-Option Standardwert Beschreibung
AccessTokenProvider null Eine Funktion, die eine Zeichenfolge zurückgibt, die als Bearerauthentifizierungstoken in HTTP-Anforderungen bereitgestellt wird.
SkipNegotiation false Legen Sie diese auf true fest, um den Aushandlungsschritt zu überspringen. Nur unterstützt, wenn der WebSockets-Transport der einzige aktivierte Transport ist. Diese Einstellung kann nicht aktiviert werden, wenn Sie Azure SignalR Service verwenden.
ClientCertificates Empty Eine Sammlung von TLS-Zertifikaten, die zur Authentifizierung von Anforderungen gesendet werden.
Cookies Empty Eine Sammlung von HTTP-Cookies, die mit jeder HTTP-Anforderung gesendet wird.
Credentials Empty Anmeldeinformationen, die mit jeder HTTP-Anforderung gesendet werden sollen.
CloseTimeout 5 Sekunden Nur WebSockets. Die maximale Zeitspanne, die der Client nach dem Schließen wartet, bis der Server die Anforderung zum Schließen bestätigt hat. Wenn der Server das Schließen nicht innerhalb dieser Zeit bestätigt, wird die Verbindung des Clients getrennt.
Headers Empty Eine Karte mit zusätzlichen HTTP-Headern, die mit jeder HTTP-Anforderung gesendet werden sollen.
HttpMessageHandlerFactory null Ein Delegat, der verwendet werden kann, um die zum Senden von HTTP-Anforderungen verwendeten HttpMessageHandler zu konfigurieren oder zu ersetzen. Wird nicht für WebSocket-Verbindungen verwendet. Dieser Delegat muss einen Wert ungleich NULL zurückgeben und empfängt den Standardwert als Parameter. Ändern Sie entweder die Einstellungen für diesen Standardwert und geben ihn zurück, oder geben Sie eine neue HttpMessageHandler-Instanz zurück. Wenn Sie den Handler ersetzen, stellen Sie sicher, dass Sie die Einstellungen, die Sie beibehalten möchten, aus dem bereitgestellten Handler kopieren. Andernfalls werden die konfigurierten Optionen (wie Cookies und Header) nicht für den neuen Handler übernommen.
Proxy null Ein HTTP-Proxy, der beim Senden von HTTP-Anforderungen verwendet werden soll.
UseDefaultCredentials false Legen Sie diesen booleschen Wert fest, um die Standardanmeldeinformationen für HTTP- und WebSockets-Anforderungen zu senden. Dies ermöglicht die Verwendung der Windows-Authentifizierung.
WebSocketConfiguration null Ein Delegat, der zum Konfigurieren zusätzlicher WebSocket-Optionen verwendet werden kann. Erhält eine Instanz von ClientWebSocketOptions, die zur Konfiguration der Optionen verwendet werden kann.
ApplicationMaxBufferSize 1 MB Die maximale Anzahl der vom Server empfangenen Bytes, die der Client puffert, bevor er Gegendruck anwendet. Eine Erhöhung dieses Werts ermöglicht es dem Client, größere Nachrichten schneller zu empfangen, ohne Gegendruck auszuüben, kann aber den Arbeitsspeicherverbrauch erhöhen.
TransportMaxBufferSize 1 MB Die maximale Anzahl von Bytes, die von der Benutzeranwendung gesendet werden, die der Client vor der Beobachtung eines Gegendrucks puffert. Wenn Sie diesen Wert erhöhen, kann der Client größere Nachrichten schneller zwischenspeichern, ohne einen Gegendruck zu erwarten, was jedoch den Speicherverbrauch erhöhen kann.

Im .NET-Client können diese Optionen durch den Optionsdelegaten geändert werden, der WithUrl zur Verfügung gestellt wird:

var connection = new HubConnectionBuilder()
    .WithUrl("https://example.com/chathub", options => {
        options.Headers["Foo"] = "Bar";
        options.SkipNegotiation = true;
        options.Transports = HttpTransportType.WebSockets;
        options.Cookies.Add(new Cookie(/* ... */);
        options.ClientCertificates.Add(/* ... */);
    })
    .Build();

Im JavaScript-Client können diese Optionen in einem JavaScript-Objekt bereitgestellt werden, das für withUrl bereitgestellt wird:

let connection = new signalR.HubConnectionBuilder()
    .withUrl("/chathub", {
        // "Foo: Bar" will not be sent with WebSockets or Server-Sent Events requests
        headers: { "Foo": "Bar" },
        transport: signalR.HttpTransportType.LongPolling 
    })
    .build();

Im Java-Client können diese Optionen mit den Methoden auf dem HttpHubConnectionBuilder konfiguriert werden, die von der HubConnectionBuilder.create("HUB URL") zurückgegeben werden.

HubConnection hubConnection = HubConnectionBuilder.create("https://example.com/chathub")
        .withHeader("Foo", "Bar")
        .shouldSkipNegotiate(true)
        .withHandshakeResponseTimeout(30*1000)
        .build();

Zusätzliche Ressourcen