SignalR-Konfiguration in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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.

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();

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:

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();

var connection = new signalR.HubConnectionBuilder()
  .withUrl("/chatHub")
  .withServerTimeout(60000)
  .withKeepAliveInterval(30000)
  .build();

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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();

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:

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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();

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:

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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.

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();

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:

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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.

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();

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:

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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.

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();

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:

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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.

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();

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:

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core

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();

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.

Konfigurieren von Serveroptionen

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

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:

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

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

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.

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.

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();

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:

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:

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

• Erste Schritte mit ASP.NET Core SignalR
• Verwenden von Hubs in in ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• ASP.NET Core SignalR .NET-Client
• Verwenden von MessagePack Hub Protocol in SignalR für ASP.NET Core
• Von SignalR unterstützte Plattformen in ASP.NET Core