Verwenden von Hubs in SignalR für ASP.NET Core

Von Rachel Appel und Kevin Griffin

Die SignalR Hubs-API ermöglicht es verbundenen Clients, Methoden auf dem Server aufzurufen, wodurch die Kommunikation in Echtzeit erleichtert wird. Der Server definiert Methoden, die vom Client aufgerufen werden, und der Client definiert Methoden, die vom Server aufgerufen werden. SignalR ermöglicht auch eine indirekte Kommunikation von Client zu Client, die immer durch den SignalR Hub vermittelt wird, so dass Nachrichten zwischen einzelnen Clients, Gruppen oder an alle verbundenen Clients gesendet werden können. SignalR kümmert sich um alles, was erforderlich ist, um die Kommunikation zwischen Client und Server sowie zwischen Server und Client in Echtzeit zu ermöglichen.

Konfigurieren von SignalR-Hubs

Rufen Sie zum Registrieren der für SignalR-Hubs erforderlichen Dienste AddSignalR in Program.cs auf:

var builder = WebApplication.CreateBuilder(args);

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

Rufen Sie zum Konfigurieren von SignalR-Endpunkten MapHub (auch in Program.cs) auf:

app.MapRazorPages();
app.MapHub<ChatHub>("/Chat");

app.Run();

Erstellen und Verwenden von Hubs

Erstellen Sie einen Hub, indem Sie eine Klasse deklarieren, die von Hub erbt. Fügen Sie der Klasse public-Methoden hinzu, um sie von Clients aus aufrufbar zu machen:

public class ChatHub : Hub
{
    public async Task SendMessage(string user, string message)
        => await Clients.All.SendAsync("ReceiveMessage", user, message);
}

Das Context-Objekt

Die Hub-Klasse enthält eine Context-Eigenschaft, die die folgenden Eigenschaften mit Informationen zur Verbindung enthält:

Hub.Context enthält auch die folgenden Methoden:

Das Clients-Objekt

Die Hub-Klasse enthält eine Clients-Eigenschaft, die die folgenden Eigenschaften für die Kommunikation zwischen Server und Client enthält:

Hub.Clients enthält auch die folgenden Methoden:

Jede Eigenschaft oder Methode in den vorherigen Tabellen gibt ein Objekt mit einer SendAsync-Methode zurück. Die SendAsync-Methode empfängt den Namen der aufzurufenden Clientmethode und alle Parameter.

Das von den Client und Caller-Methoden zurückgegebene Objekt enthält auch eine InvokeAsync-Methode, die verwendet werden kann, um auf ein Ergebnis vom Client zu warten.

Senden von Nachrichten an Clients

Verwenden Sie die Eigenschaften des Clients-Objekts, um Aufrufe für bestimmte Clients auszuführen. Im folgenden Beispiel gibt es drei Hubmethoden:

• SendMessage sendet mithilfe von Clients.All eine Nachricht an alle verbundenen Clients .
• SendMessageToCaller sendet mithilfe von Clients.Caller eine Nachricht zurück an den Aufrufer.
• SendMessageToGroup sendet eine Nachricht an alle Clients in der SignalR Users-Gruppe.

public async Task SendMessage(string user, string message)
    => await Clients.All.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToCaller(string user, string message)
    => await Clients.Caller.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToGroup(string user, string message)
    => await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);

Stark typisierte Hubs

Ein Nachteil der Verwendung von SendAsync besteht darin, dass eine Zeichenfolge erforderlich ist, um die Clientmethode anzugeben, die aufgerufen werden soll. Dadurch kann es zu Laufzeitfehlern kommen, wenn der Methodenname falsch geschrieben ist oder im Client fehlt.

Eine Alternative zur Verwendung von SendAsync besteht darin, die Hub-Klasse mit Hub<T> stark zu typisieren. Im folgenden Beispiel wurde die ChatHub-Clientmethode in eine Schnittstelle namens IChatClient extrahiert:

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

Diese Schnittstelle kann verwendet werden, um das vorherige ChatHub-Beispiel so umzugestalten, dass es stark typisiert ist:

public class StronglyTypedChatHub : Hub<IChatClient>
{
    public async Task SendMessage(string user, string message)
        => await Clients.All.ReceiveMessage(user, message);

    public async Task SendMessageToCaller(string user, string message)
        => await Clients.Caller.ReceiveMessage(user, message);

    public async Task SendMessageToGroup(string user, string message)
        => await Clients.Group("SignalR Users").ReceiveMessage(user, message);
}

Die Verwendung von Hub<IChatClient> ermöglicht die Überprüfung der Clientmethoden zur Kompilierzeit. Dadurch werden Probleme verhindert, die durch die Verwendung von Zeichenfolgen verursacht werden, weil Hub<T> nur Zugriff auf die in der Schnittstelle definierten Methoden bereitstellen kann. Die Verwendung eines stark typisierten Hub<T> deaktiviert die Möglichkeit, SendAsync zu verwenden.

Clientergebnisse

Zusätzlich zu Aufrufen von Clients kann der Server ein Ergebnis von einem Client anfordern. Dazu muss der Server ISingleClientProxy.InvokeAsync verwenden, und der Client muss ein Ergebnis aus seinem .On-Handler zurückzugeben.

Es gibt zwei Möglichkeiten, die API auf dem Server zu verwenden: Die erste besteht darin, Client(...) oder Caller für die Clients-Eigenschaft in einer Hub-Methode aufzurufen:

public class ChatHub : Hub
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        var message = await Clients.Client(connectionId).InvokeAsync<string>(
            "GetMessage");
        return message;
    }
}

Die zweite Möglichkeit besteht darin, Client(...) für eine Instanz von IHubContext<T> aufzurufen:

async Task SomeMethod(IHubContext<MyHub> context)
{
    string result = await context.Clients.Client(connectionID).InvokeAsync<string>(
        "GetMessage");
}

Stark typisierte Hubs können auch Werte aus Schnittstellenmethoden zurückgeben:

public interface IClient
{
    Task<string> GetMessage();
}

public class ChatHub : Hub<IClient>
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        string message = await Clients.Client(connectionId).GetMessage();
        return message;
    }
}

Clients geben Ergebnisse in ihren .On(...)-Handlern zurück, wie unten gezeigt:

.NET-Client

hubConnection.On("GetMessage", async () =>
{
    Console.WriteLine("Enter message:");
    var message = await Console.In.ReadLineAsync();
    return message;
});

TypeScript-Client

hubConnection.on("GetMessage", async () => {
    let promise = new Promise((resolve, reject) => {
        setTimeout(() => {
            resolve("message");
        }, 100);
    });
    return promise;
});

Java-Client

hubConnection.onWithResult("GetMessage", () -> {
    return Single.just("message");
});

Ändern des Namens einer Hubmethode

Standardmäßig ist der Name einer Serverhubmethode der Name der .NET-Methode. Um dieses Standardverhalten für eine bestimmte Methode zu ändern, verwenden Sie das HubMethodName-Attribut. Der Client sollte diesen Namen anstelle des .NET-Methodennamens verwenden, wenn die Methode aufgerufen wird:

[HubMethodName("SendMessageToUser")]
public async Task DirectMessage(string user, string message)
    => await Clients.User(user).SendAsync("ReceiveMessage", user, message);

Einfügen von Diensten in einen Hub

Hubkonstruktoren können Dienste der Abhängigkeitsinjektion als Parameter akzeptieren, die in Eigenschaften der Klasse zur Verwendung in einer Hubmethode gespeichert werden können.

Beim Einfügen mehrerer Dienste für verschiedene Hubmethoden oder als alternatives Verfahren zum Schreiben von Code können Hubmethoden auch Dienste von DI akzeptieren. Standardmäßig werden Hubmethodenparameter überprüft und nach Möglichkeit von DI aufgelöst.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message, IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Wenn die implizite Auflösung von Parametern aus Diensten nicht gewünscht ist, deaktivieren Sie sie mit DisableImplicitFromServicesParameters. Um explizit anzugeben, welche Parameter in Hubmethoden von DI aufgelöst werden, verwenden Sie die Option DisableImplicitFromServicesParameters und das Attribut [FromServices] oder ein benutzerdefiniertes Attribut, das IFromServiceMetadata implementiert, für die Parameter der Hubmethode, die von DI aufgelöst werden sollen.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();
services.AddSignalR(options =>
{
    options.DisableImplicitFromServicesParameters = true;
});

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message,
        [FromServices] IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Unterstützung von Schlüsseldiensten in Abhängigkeitsinjektion

Schlüsseldienste bezieht sich auf einen Mechanismus für die Registrierung und den Abruf von Dependency Injection (DI) Services unter Verwendung von Schlüsseln. Ein Dienst wird mit einem Schlüssel verknüpft, indem Sie AddKeyedSingleton (oder AddKeyedScoped oder AddKeyedTransient) aufrufen, um ihn zu registrieren. Greifen Sie auf einen registrierten Dienst zu, indem Sie den Schlüssel mit dem [FromKeyedServices] Attribut angeben. Der folgende Code zeigt, wie Sie Schlüsseldienste verwenden können:

using Microsoft.AspNetCore.SignalR;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeyedSingleton<ICache, BigCache>("big");
builder.Services.AddKeyedSingleton<ICache, SmallCache>("small");

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

var app = builder.Build();

app.MapRazorPages();
app.MapHub<MyHub>("/myHub");

app.Run();

public interface ICache
{
    object Get(string key);
}
public class BigCache : ICache
{
    public object Get(string key) => $"Resolving {key} from big cache.";
}

public class SmallCache : ICache
{
    public object Get(string key) => $"Resolving {key} from small cache.";
}

public class MyHub : Hub
{
    public void SmallCacheMethod([FromKeyedServices("small")] ICache cache)
    {
        Console.WriteLine(cache.Get("signalr"));
    }

    public void BigCacheMethod([FromKeyedServices("big")] ICache cache)
    {
        Console.WriteLine(cache.Get("signalr"));
    }
}

Behandeln von Ereignissen für eine Verbindung

Die Hubs-API von SignalR stellt die virtuellen OnConnectedAsync- und OnDisconnectedAsync-Methoden zum Verwalten und Nachverfolgen von Verbindungen bereit. Überschreiben Sie die virtuelle OnConnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client eine Verbindung mit dem Hub herstellt, ihn z. B. einer Gruppe hinzufügt:

public override async Task OnConnectedAsync()
{
    await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnConnectedAsync();
}

Überschreiben Sie die virtuelle OnDisconnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client die Verbindung trennt. Wenn der Client die Verbindung absichtlich trennt, z. B. durch Aufrufen von connection.stop(), wird der exception-Parameter auf null festgelegt. Wenn der Client jedoch aufgrund eines Fehlers (z. B. eines Netzwerkfehlers) die Verbindung trennt, enthält der exception-Parameter eine Ausnahme, die den Fehler beschreibt:

public override async Task OnDisconnectedAsync(Exception? exception)
{
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync muss in OnDisconnectedAsync nicht aufgerufen werden, es wird automatisch für Sie verarbeitet.

Umgang mit Fehlern

Ausnahmen, die in Hubmethoden ausgelöst werden, werden an den Client gesendet, der die Methode aufgerufen hat. Auf dem JavaScript-Client gibt die invoke-Methode eine JavaScript-Promise zurück. Clients können einen catch-Handler an die zurückgegebene Zusage anfügen oder try/catch mit async/await verwenden, um Ausnahmen zu behandeln:

try {
  await connection.invoke("SendMessage", user, message);
} catch (err) {
  console.error(err);
}

Verbindungen werden nicht geschlossen, wenn ein Hub eine Ausnahme auslöst. SignalR gibt standardmäßig eine generische Fehlermeldung an den Client zurück, wie im folgenden Beispiel gezeigt:

Microsoft.AspNetCore.SignalR.HubException: An unexpected error occurred invoking 'SendMessage' on the server.

Unerwartete Ausnahmen enthalten häufig vertrauliche Informationen, z. B. den Namen eines Datenbankservers in einer Ausnahme, die ausgelöst wird, wenn die Datenbankverbindung fehlschlägt. SignalR stellt diese detaillierten Fehlermeldungen als Sicherheitsmaßnahme standardmäßig nicht zur Verfügung. Weitere Informationen dazu, warum Ausnahmedetails unterdrückt werden, finden Sie unter Sicherheitsüberlegungen in ASP.NET Core SignalR.

Wenn eine Ausnahmebedingung an den Client weitergegeben werden muss, verwenden Sie die HubException-Klasse. Wenn eine HubException in einer Hubmethode ausgelöst wird, SignalRsendet die gesamte Ausnahmemeldung an den Client (unverändert):

public Task ThrowException()
    => throw new HubException("This error will be sent to the client!");

Zusätzliche Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Übersicht über ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• Veröffentlichen einer ASP.NET Core-SignalR-App bei Azure App Service

Von Rachel Appel und Kevin Griffin

Die SignalR Hubs-API ermöglicht es verbundenen Clients, Methoden auf dem Server aufzurufen, wodurch die Kommunikation in Echtzeit erleichtert wird. Der Server definiert Methoden, die vom Client aufgerufen werden, und der Client definiert Methoden, die vom Server aufgerufen werden. SignalR ermöglicht auch eine indirekte Kommunikation von Client zu Client, die immer durch den SignalR Hub vermittelt wird, so dass Nachrichten zwischen einzelnen Clients, Gruppen oder an alle verbundenen Clients gesendet werden können. SignalR kümmert sich um alles, was erforderlich ist, um die Kommunikation zwischen Client und Server sowie zwischen Server und Client in Echtzeit zu ermöglichen.

Konfigurieren von SignalR-Hubs

Rufen Sie zum Registrieren der für SignalR-Hubs erforderlichen Dienste AddSignalR in Program.cs auf:

var builder = WebApplication.CreateBuilder(args);

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

Rufen Sie zum Konfigurieren von SignalR-Endpunkten MapHub (auch in Program.cs) auf:

app.MapRazorPages();
app.MapHub<ChatHub>("/Chat");

app.Run();

Erstellen und Verwenden von Hubs

Erstellen Sie einen Hub, indem Sie eine Klasse deklarieren, die von Hub erbt. Fügen Sie der Klasse public-Methoden hinzu, um sie von Clients aus aufrufbar zu machen:

public class ChatHub : Hub
{
    public async Task SendMessage(string user, string message)
        => await Clients.All.SendAsync("ReceiveMessage", user, message);
}

Das Context-Objekt

Die Hub-Klasse enthält eine Context-Eigenschaft, die die folgenden Eigenschaften mit Informationen zur Verbindung enthält:

Hub.Context enthält auch die folgenden Methoden:

Das Clients-Objekt

Die Hub-Klasse enthält eine Clients-Eigenschaft, die die folgenden Eigenschaften für die Kommunikation zwischen Server und Client enthält:

Hub.Clients enthält auch die folgenden Methoden:

Jede Eigenschaft oder Methode in den vorherigen Tabellen gibt ein Objekt mit einer SendAsync-Methode zurück. Die SendAsync-Methode empfängt den Namen der aufzurufenden Clientmethode und alle Parameter.

Das von den Client und Caller-Methoden zurückgegebene Objekt enthält auch eine InvokeAsync-Methode, die verwendet werden kann, um auf ein Ergebnis vom Client zu warten.

Senden von Nachrichten an Clients

Verwenden Sie die Eigenschaften des Clients-Objekts, um Aufrufe für bestimmte Clients auszuführen. Im folgenden Beispiel gibt es drei Hubmethoden:

• SendMessage sendet mithilfe von Clients.All eine Nachricht an alle verbundenen Clients .
• SendMessageToCaller sendet mithilfe von Clients.Caller eine Nachricht zurück an den Aufrufer.
• SendMessageToGroup sendet eine Nachricht an alle Clients in der SignalR Users-Gruppe.

public async Task SendMessage(string user, string message)
    => await Clients.All.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToCaller(string user, string message)
    => await Clients.Caller.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToGroup(string user, string message)
    => await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);

Stark typisierte Hubs

Ein Nachteil der Verwendung von SendAsync besteht darin, dass eine Zeichenfolge erforderlich ist, um die Clientmethode anzugeben, die aufgerufen werden soll. Dadurch kann es zu Laufzeitfehlern kommen, wenn der Methodenname falsch geschrieben ist oder im Client fehlt.

Eine Alternative zur Verwendung von SendAsync besteht darin, die Hub-Klasse mit Hub<T> stark zu typisieren. Im folgenden Beispiel wurde die ChatHub-Clientmethode in eine Schnittstelle namens IChatClient extrahiert:

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

Diese Schnittstelle kann verwendet werden, um das vorherige ChatHub-Beispiel so umzugestalten, dass es stark typisiert ist:

public class StronglyTypedChatHub : Hub<IChatClient>
{
    public async Task SendMessage(string user, string message)
        => await Clients.All.ReceiveMessage(user, message);

    public async Task SendMessageToCaller(string user, string message)
        => await Clients.Caller.ReceiveMessage(user, message);

    public async Task SendMessageToGroup(string user, string message)
        => await Clients.Group("SignalR Users").ReceiveMessage(user, message);
}

Die Verwendung von Hub<IChatClient> ermöglicht die Überprüfung der Clientmethoden zur Kompilierzeit. Dadurch werden Probleme verhindert, die durch die Verwendung von Zeichenfolgen verursacht werden, weil Hub<T> nur Zugriff auf die in der Schnittstelle definierten Methoden bereitstellen kann. Die Verwendung eines stark typisierten Hub<T> deaktiviert die Möglichkeit, SendAsync zu verwenden.

Clientergebnisse

Zusätzlich zu Aufrufen von Clients kann der Server ein Ergebnis von einem Client anfordern. Dazu muss der Server ISingleClientProxy.InvokeAsync verwenden, und der Client muss ein Ergebnis aus seinem .On-Handler zurückzugeben.

Es gibt zwei Möglichkeiten, die API auf dem Server zu verwenden: Die erste besteht darin, Client(...) oder Caller für die Clients-Eigenschaft in einer Hub-Methode aufzurufen:

public class ChatHub : Hub
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        var message = await Clients.Client(connectionId).InvokeAsync<string>(
            "GetMessage");
        return message;
    }
}

Die zweite Möglichkeit besteht darin, Client(...) für eine Instanz von IHubContext<T> aufzurufen:

async Task SomeMethod(IHubContext<MyHub> context)
{
    string result = await context.Clients.Client(connectionID).InvokeAsync<string>(
        "GetMessage");
}

Stark typisierte Hubs können auch Werte aus Schnittstellenmethoden zurückgeben:

public interface IClient
{
    Task<string> GetMessage();
}

public class ChatHub : Hub<IClient>
{
    public async Task<string> WaitForMessage(string connectionId)
    {
        string message = await Clients.Client(connectionId).GetMessage();
        return message;
    }
}

Clients geben Ergebnisse in ihren .On(...)-Handlern zurück, wie unten gezeigt:

.NET-Client

hubConnection.On("GetMessage", async () =>
{
    Console.WriteLine("Enter message:");
    var message = await Console.In.ReadLineAsync();
    return message;
});

TypeScript-Client

hubConnection.on("GetMessage", async () => {
    let promise = new Promise((resolve, reject) => {
        setTimeout(() => {
            resolve("message");
        }, 100);
    });
    return promise;
});

Java-Client

hubConnection.onWithResult("GetMessage", () -> {
    return Single.just("message");
});

Ändern des Namens einer Hubmethode

Standardmäßig ist der Name einer Serverhubmethode der Name der .NET-Methode. Um dieses Standardverhalten für eine bestimmte Methode zu ändern, verwenden Sie das HubMethodName-Attribut. Der Client sollte diesen Namen anstelle des .NET-Methodennamens verwenden, wenn die Methode aufgerufen wird:

[HubMethodName("SendMessageToUser")]
public async Task DirectMessage(string user, string message)
    => await Clients.User(user).SendAsync("ReceiveMessage", user, message);

Einfügen von Diensten in einen Hub

Hubkonstruktoren können Dienste der Abhängigkeitsinjektion als Parameter akzeptieren, die in Eigenschaften der Klasse zur Verwendung in einer Hubmethode gespeichert werden können.

Beim Einfügen mehrerer Dienste für verschiedene Hubmethoden oder als alternatives Verfahren zum Schreiben von Code können Hubmethoden auch Dienste von DI akzeptieren. Standardmäßig werden Hubmethodenparameter überprüft und nach Möglichkeit von DI aufgelöst.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message, IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Wenn die implizite Auflösung von Parametern aus Diensten nicht gewünscht ist, deaktivieren Sie sie mit DisableImplicitFromServicesParameters. Um explizit anzugeben, welche Parameter in Hubmethoden von DI aufgelöst werden, verwenden Sie die Option DisableImplicitFromServicesParameters und das Attribut [FromServices] oder ein benutzerdefiniertes Attribut, das IFromServiceMetadata implementiert, für die Parameter der Hubmethode, die von DI aufgelöst werden sollen.

services.AddSingleton<IDatabaseService, DatabaseServiceImpl>();
services.AddSignalR(options =>
{
    options.DisableImplicitFromServicesParameters = true;
});

// ...

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message,
        [FromServices] IDatabaseService dbService)
    {
        var userName = dbService.GetUserName(user);
        return Clients.All.SendAsync("ReceiveMessage", userName, message);
    }
}

Behandeln von Ereignissen für eine Verbindung

Die Hubs-API von SignalR stellt die virtuellen OnConnectedAsync- und OnDisconnectedAsync-Methoden zum Verwalten und Nachverfolgen von Verbindungen bereit. Überschreiben Sie die virtuelle OnConnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client eine Verbindung mit dem Hub herstellt, ihn z. B. einer Gruppe hinzufügt:

public override async Task OnConnectedAsync()
{
    await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnConnectedAsync();
}

Überschreiben Sie die virtuelle OnDisconnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client die Verbindung trennt. Wenn der Client die Verbindung absichtlich trennt, z. B. durch Aufrufen von connection.stop(), wird der exception-Parameter auf null festgelegt. Wenn der Client jedoch aufgrund eines Fehlers (z. B. eines Netzwerkfehlers) die Verbindung trennt, enthält der exception-Parameter eine Ausnahme, die den Fehler beschreibt:

public override async Task OnDisconnectedAsync(Exception? exception)
{
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync muss nicht in OnDisconnectedAsync aufgerufen werden, das Element wird automatisch für Sie verarbeitet.

Umgang mit Fehlern

Ausnahmen, die in Hubmethoden ausgelöst werden, werden an den Client gesendet, der die Methode aufgerufen hat. Auf dem JavaScript-Client gibt die invoke-Methode eine JavaScript-Promise zurück. Clients können einen catch-Handler an die zurückgegebene Zusage anfügen oder try/catch mit async/await verwenden, um Ausnahmen zu behandeln:

try {
  await connection.invoke("SendMessage", user, message);
} catch (err) {
  console.error(err);
}

Verbindungen werden nicht geschlossen, wenn ein Hub eine Ausnahme auslöst. SignalR gibt standardmäßig eine generische Fehlermeldung an den Client zurück, wie im folgenden Beispiel gezeigt:

Microsoft.AspNetCore.SignalR.HubException: An unexpected error occurred invoking 'SendMessage' on the server.

Unerwartete Ausnahmen enthalten häufig vertrauliche Informationen, z. B. den Namen eines Datenbankservers in einer Ausnahme, die ausgelöst wird, wenn die Datenbankverbindung fehlschlägt. SignalR stellt diese detaillierten Fehlermeldungen als Sicherheitsmaßnahme standardmäßig nicht zur Verfügung. Weitere Informationen dazu, warum Ausnahmedetails unterdrückt werden, finden Sie unter Sicherheitsüberlegungen in ASP.NET Core SignalR.

Wenn eine Ausnahmebedingung an den Client weitergegeben werden muss, verwenden Sie die HubException-Klasse. Wenn eine HubException in einer Hubmethode ausgelöst wird, SignalRsendet die gesamte Ausnahmemeldung an den Client (unverändert):

public Task ThrowException()
    => throw new HubException("This error will be sent to the client!");

Zusätzliche Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Übersicht über ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• Veröffentlichen einer ASP.NET Core-SignalR-App bei Azure App Service

Von Rachel Appel und Kevin Griffin

Die SignalR Hubs-API ermöglicht es verbundenen Clients, Methoden auf dem Server aufzurufen, wodurch die Kommunikation in Echtzeit erleichtert wird. Der Server definiert Methoden, die vom Client aufgerufen werden, und der Client definiert Methoden, die vom Server aufgerufen werden. SignalR ermöglicht auch eine indirekte Kommunikation von Client zu Client, die immer durch den SignalR Hub vermittelt wird, so dass Nachrichten zwischen einzelnen Clients, Gruppen oder an alle verbundenen Clients gesendet werden können. SignalR kümmert sich um alles, was erforderlich ist, um die Kommunikation zwischen Client und Server sowie zwischen Server und Client in Echtzeit zu ermöglichen.

Konfigurieren von SignalR-Hubs

Rufen Sie zum Registrieren der für SignalR-Hubs erforderlichen Dienste AddSignalR in Program.cs auf:

var builder = WebApplication.CreateBuilder(args);

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

Rufen Sie zum Konfigurieren von SignalR-Endpunkten MapHub (auch in Program.cs) auf:

app.MapRazorPages();
app.MapHub<ChatHub>("/Chat");

app.Run();

Erstellen und Verwenden von Hubs

Erstellen Sie einen Hub, indem Sie eine Klasse deklarieren, die von Hub erbt. Fügen Sie der Klasse public-Methoden hinzu, um sie von Clients aus aufrufbar zu machen:

public class ChatHub : Hub
{
    public async Task SendMessage(string user, string message)
        => await Clients.All.SendAsync("ReceiveMessage", user, message);
}

Das Context-Objekt

Die Hub-Klasse enthält eine Context-Eigenschaft, die die folgenden Eigenschaften mit Informationen zur Verbindung enthält:

Hub.Context enthält auch die folgenden Methoden:

Das Clients-Objekt

Die Hub-Klasse enthält eine Clients-Eigenschaft, die die folgenden Eigenschaften für die Kommunikation zwischen Server und Client enthält:

Hub.Clients enthält auch die folgenden Methoden:

Jede Eigenschaft oder Methode in den vorherigen Tabellen gibt ein Objekt mit einer SendAsync-Methode zurück. Die SendAsync-Methode empfängt den Namen der aufzurufenden Clientmethode und alle Parameter.

Senden von Nachrichten an Clients

Verwenden Sie die Eigenschaften des Clients-Objekts, um Aufrufe für bestimmte Clients auszuführen. Im folgenden Beispiel gibt es drei Hubmethoden:

• SendMessage sendet mithilfe von Clients.All eine Nachricht an alle verbundenen Clients .
• SendMessageToCaller sendet mithilfe von Clients.Caller eine Nachricht zurück an den Aufrufer.
• SendMessageToGroup sendet eine Nachricht an alle Clients in der SignalR Users-Gruppe.

public async Task SendMessage(string user, string message)
    => await Clients.All.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToCaller(string user, string message)
    => await Clients.Caller.SendAsync("ReceiveMessage", user, message);

public async Task SendMessageToGroup(string user, string message)
    => await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);

Stark typisierte Hubs

Ein Nachteil der Verwendung von SendAsync besteht darin, dass eine Zeichenfolge erforderlich ist, um die Clientmethode anzugeben, die aufgerufen werden soll. Dadurch kann es zu Laufzeitfehlern kommen, wenn der Methodenname falsch geschrieben ist oder im Client fehlt.

Eine Alternative zur Verwendung von SendAsync besteht darin, die Hub-Klasse mit Hub<T> stark zu typisieren. Im folgenden Beispiel wurde die ChatHub-Clientmethode in eine Schnittstelle namens IChatClient extrahiert:

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

Diese Schnittstelle kann verwendet werden, um das vorherige ChatHub-Beispiel so umzugestalten, dass es stark typisiert ist:

public class StronglyTypedChatHub : Hub<IChatClient>
{
    public async Task SendMessage(string user, string message)
        => await Clients.All.ReceiveMessage(user, message);

    public async Task SendMessageToCaller(string user, string message)
        => await Clients.Caller.ReceiveMessage(user, message);

    public async Task SendMessageToGroup(string user, string message)
        => await Clients.Group("SignalR Users").ReceiveMessage(user, message);
}

Die Verwendung von Hub<IChatClient> ermöglicht die Überprüfung der Clientmethoden zur Kompilierzeit. Dadurch werden Probleme verhindert, die durch die Verwendung von Zeichenfolgen verursacht werden, weil Hub<T> nur Zugriff auf die in der Schnittstelle definierten Methoden bereitstellen kann. Die Verwendung eines stark typisierten Hub<T> deaktiviert die Möglichkeit, SendAsync zu verwenden.

Ändern des Namens einer Hubmethode

Standardmäßig ist der Name einer Serverhubmethode der Name der .NET-Methode. Um dieses Standardverhalten für eine bestimmte Methode zu ändern, verwenden Sie das HubMethodName-Attribut. Der Client sollte diesen Namen anstelle des .NET-Methodennamens verwenden, wenn die Methode aufgerufen wird:

[HubMethodName("SendMessageToUser")]
public async Task DirectMessage(string user, string message)
    => await Clients.User(user).SendAsync("ReceiveMessage", user, message);

Behandeln von Ereignissen für eine Verbindung

Die Hubs-API von SignalR stellt die virtuellen OnConnectedAsync- und OnDisconnectedAsync-Methoden zum Verwalten und Nachverfolgen von Verbindungen bereit. Überschreiben Sie die virtuelle OnConnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client eine Verbindung mit dem Hub herstellt, ihn z. B. einer Gruppe hinzufügt:

public override async Task OnConnectedAsync()
{
    await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnConnectedAsync();
}

Überschreiben Sie die virtuelle OnDisconnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client die Verbindung trennt. Wenn der Client die Verbindung absichtlich trennt, z. B. durch Aufrufen von connection.stop(), wird der exception-Parameter auf null festgelegt. Wenn der Client jedoch aufgrund eines Fehlers (z. B. eines Netzwerkfehlers) die Verbindung trennt, enthält der exception-Parameter eine Ausnahme, die den Fehler beschreibt:

public override async Task OnDisconnectedAsync(Exception? exception)
{
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync muss nicht in OnDisconnectedAsync aufgerufen werden, das Element wird automatisch für Sie verarbeitet.

Umgang mit Fehlern

Ausnahmen, die in Hubmethoden ausgelöst werden, werden an den Client gesendet, der die Methode aufgerufen hat. Auf dem JavaScript-Client gibt die invoke-Methode eine JavaScript-Promise zurück. Clients können einen catch-Handler an die zurückgegebene Zusage anfügen oder try/catch mit async/await verwenden, um Ausnahmen zu behandeln:

try {
  await connection.invoke("SendMessage", user, message);
} catch (err) {
  console.error(err);
}

Verbindungen werden nicht geschlossen, wenn ein Hub eine Ausnahme auslöst. SignalR gibt standardmäßig eine generische Fehlermeldung an den Client zurück, wie im folgenden Beispiel gezeigt:

Microsoft.AspNetCore.SignalR.HubException: An unexpected error occurred invoking 'SendMessage' on the server.

Unerwartete Ausnahmen enthalten häufig vertrauliche Informationen, z. B. den Namen eines Datenbankservers in einer Ausnahme, die ausgelöst wird, wenn die Datenbankverbindung fehlschlägt. SignalR stellt diese detaillierten Fehlermeldungen als Sicherheitsmaßnahme standardmäßig nicht zur Verfügung. Weitere Informationen dazu, warum Ausnahmedetails unterdrückt werden, finden Sie unter Sicherheitsüberlegungen in ASP.NET Core SignalR.

Wenn eine Ausnahmebedingung an den Client weitergegeben werden muss, verwenden Sie die HubException-Klasse. Wenn eine HubException in einer Hubmethode ausgelöst wird, SignalRsendet die gesamte Ausnahmemeldung an den Client (unverändert):

public Task ThrowException()
    => throw new HubException("This error will be sent to the client!");

Zusätzliche Ressourcen

• Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)
• Übersicht über ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• Veröffentlichen einer ASP.NET Core-SignalR-App bei Azure App Service
• SignalR-Hubprotokoll

Von Rachel Appel und Kevin Griffin

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Was ist ein SignalR-Hub?

Die SignalR Hubs-API ermöglicht es verbundenen Clients, Methoden auf dem Server aufzurufen, wodurch die Kommunikation in Echtzeit erleichtert wird. Der Server definiert Methoden, die vom Client aufgerufen werden, und der Client definiert Methoden, die vom Server aufgerufen werden. SignalR ermöglicht auch eine indirekte Kommunikation von Client zu Client, die immer durch den SignalR Hub vermittelt wird, so dass Nachrichten zwischen einzelnen Clients, Gruppen oder an alle verbundenen Clients gesendet werden können. SignalR kümmert sich um alles, was erforderlich ist, um die Kommunikation zwischen Client und Server sowie zwischen Server und Client in Echtzeit zu ermöglichen.

Konfigurieren von SignalR-Hubs

Die SignalR-Middleware erfordert einige Dienste, die durch Aufrufe von AddSignalR konfiguriert werden:

services.AddSignalR();

Wenn Sie einer ASP.NET Core-App SignalR-Funktionen hinzufügen, richten Sie SignalR-Routen ein, indem Sie MapHub im UseEndpoints-Rückruf der Startup.Configure-Methode aufrufen:

app.UseRouting();
app.UseEndpoints(endpoints =>
{
    endpoints.MapHub<ChatHub>("/chathub");
});

Erstellen und Verwenden von Hubs

Erstellen Sie einen Hub, indem Sie eine Klasse deklarieren, die von Hub erbt, und fügen Sie ihr öffentliche Methoden hinzu. Clients können Methoden aufrufen, die als public definiert sind:

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message)
    {
        return Clients.All.SendAsync("ReceiveMessage", user, message);
    }
}

Sie können wie in jeder C#-Methode einen Rückgabetyp und Parameter angeben, auch komplexe Typen und Arrays. SignalR behandelt die Serialisierung und Deserialisierung komplexer Objekte und Arrays in Ihren Parametern und Rückgabewerten.

Das Context-Objekt

Die Hub-Klasse verfügt über eine Context-Eigenschaft, die die folgenden Eigenschaften mit Informationen zur Verbindung enthält:

Hub.Context enthält auch die folgenden Methoden:

Das Clients-Objekt

Die Hub-Klasse verfügt über eine Clients-Eigenschaft, die die folgenden Eigenschaften für die Kommunikation zwischen Server und Client enthält:

Hub.Clients enthält auch die folgenden Methoden:

Jede Eigenschaft oder Methode in den vorherigen Tabellen gibt ein Objekt mit einer SendAsync-Methode zurück. Mit der SendAsync-Methode können Sie den Namen und die Parameter der Clientmethode angeben, die aufgerufen werden soll.

Senden von Nachrichten an Clients

Verwenden Sie die Eigenschaften des Clients-Objekts, um Aufrufe für bestimmte Clients auszuführen. Im folgenden Beispiel gibt es drei Hubmethoden:

• SendMessage sendet mithilfe von Clients.All eine Nachricht an alle verbundenen Clients .
• SendMessageToCaller sendet mithilfe von Clients.Caller eine Nachricht zurück an den Aufrufer.
• SendMessageToGroup sendet eine Nachricht an alle Clients in der SignalR Users-Gruppe.

public Task SendMessage(string user, string message)
{
    return Clients.All.SendAsync("ReceiveMessage", user, message);
}

public Task SendMessageToCaller(string user, string message)
{
    return Clients.Caller.SendAsync("ReceiveMessage", user, message);
}

public Task SendMessageToGroup(string user, string message)
{
    return Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);
}

Stark typisierte Hubs

Ein Nachteil der Verwendung von SendAsync besteht darin, dass eine magische Zeichenfolge erforderlich ist, um die Clientmethode anzugeben, die aufgerufen werden soll. Dadurch kann es zu Laufzeitfehlern kommen, wenn der Methodenname falsch geschrieben ist oder im Client fehlt.

Eine Alternative zur Verwendung von SendAsync besteht darin, die Hub-Klasse mit Hub<T> stark zu typisieren. Im folgenden Beispiel wurden die ChatHub-Clientmethoden in eine Schnittstelle namens IChatClient extrahiert.

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

Diese Schnittstelle kann verwendet werden, um das vorherige ChatHub-Beispiel umzugestalten:

    public class StronglyTypedChatHub : Hub<IChatClient>
    {
        public async Task SendMessage(string user, string message)
        {
            await Clients.All.ReceiveMessage(user, message);
        }

        public Task SendMessageToCaller(string user, string message)
        {
            return Clients.Caller.ReceiveMessage(user, message);
        }
}

Die Verwendung von Hub<IChatClient> ermöglicht die Überprüfung der Clientmethoden zur Kompilierzeit. Dadurch werden Probleme verhindert, die durch die Verwendung von magischen Zeichenfolgen verursacht werden, weil Hub<T> nur Zugriff auf die in der Schnittstelle definierten Methoden bereitstellen kann.

Die Verwendung eines stark typisierten Hub<T> deaktiviert die Möglichkeit, SendAsync zu verwenden. Alle Methoden, die für die Schnittstelle definiert sind, können weiterhin als asynchron definiert werden. Tatsächlich sollte jede dieser Methoden einen Task zurückgeben. Da es sich um eine Schnittstelle handelt, verwenden Sie nicht das async-Schlüsselwort. Beispiel:

public interface IClient
{
    Task ClientMethod();
}

Ändern des Namens einer Hubmethode

Standardmäßig ist der Name einer Serverhubmethode der Name der .NET-Methode. Sie können jedoch das HubMethodName-Attribut verwenden, um diese Standardeinstellung zu ändern und manuell einen Namen für die Methode anzugeben. Der Client sollte diesen Namen anstelle des .NET-Methodennamens verwenden, wenn die Methode aufgerufen wird:

[HubMethodName("SendMessageToUser")]
public Task DirectMessage(string user, string message)
{
    return Clients.User(user).SendAsync("ReceiveMessage", user, message);
}

Behandeln von Ereignissen für eine Verbindung

Die Hubs-API von SignalR stellt die virtuellen OnConnectedAsync- und OnDisconnectedAsync-Methoden zum Verwalten und Nachverfolgen von Verbindungen bereit. Überschreiben Sie die virtuelle OnConnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client eine Verbindung mit dem Hub herstellt, ihn z. B. einer Gruppe hinzufügt:

public override async Task OnConnectedAsync()
{
    await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnConnectedAsync();
}

Überschreiben Sie die virtuelle OnDisconnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client die Verbindung trennt. Wenn der Client die Verbindung absichtlich trennt (z. B. durch Aufrufen von connection.stop()), lautet der exception-Parameter null. Wenn der Client jedoch aufgrund eines Fehlers getrennt wird (z. B. durch einen Netzwerkfehler), enthält der exception-Parameter eine Ausnahme, die den Fehler beschreibt:

public override async Task OnDisconnectedAsync(Exception exception)
{
    await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", "I", "disconnect");
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync muss nicht in OnDisconnectedAsync aufgerufen werden, das Element wird automatisch für Sie verarbeitet.

Umgang mit Fehlern

Ausnahmen, die in Ihren Hubmethoden ausgelöst werden, werden an den Client gesendet, der die Methode aufgerufen hat. Auf dem JavaScript-Client gibt die invoke-Methode eine JavaScript-Promise zurück. Wenn der Client einen Fehler mit einem an die Zusage angefügten Handler mit catch empfängt, wird er aufgerufen und als JavaScript-Error-Objekt übergeben:

connection.invoke("SendMessage", user, message).catch(err => console.error(err));

Wenn Ihr Hub eine Ausnahme auslöst, werden Verbindungen nicht geschlossen. SignalR gibt standardmäßig eine generische Fehlermeldung an den Client zurück. Beispiel:

Microsoft.AspNetCore.SignalR.HubException: An unexpected error occurred invoking 'MethodName' on the server.

Unerwartete Ausnahmen enthalten häufig vertrauliche Informationen, z. B. den Namen eines Datenbankservers in einer Ausnahme, die ausgelöst wird, wenn die Datenbankverbindung fehlschlägt. SignalR stellt diese detaillierten Fehlermeldungen als Sicherheitsmaßnahme standardmäßig nicht zur Verfügung. Weitere Informationen dazu, warum Ausnahmedetails unterdrückt werden, finden Sie unter Sicherheitsüberlegungen in ASP.NET Core SignalR.

Wenn Sie eine außergewöhnliche Bedingung haben, die Sie an den Client weitergeben möchten, können Sie die HubException-Klasse verwenden. Wenn Sie eine HubException aus Ihrer Hubmethode auslösen, sendetSignalR die gesamte Nachricht unverändert an den Client:

public Task ThrowException()
{
    throw new HubException("This error will be sent to the client!");
}

Zusätzliche Ressourcen

• Übersicht über ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• Veröffentlichen einer ASP.NET Core-SignalR-App bei Azure App Service

Von Rachel Appel und Kevin Griffin

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Was ist ein SignalR-Hub?

Die SignalR Hubs-API ermöglicht es verbundenen Clients, Methoden auf dem Server aufzurufen, wodurch die Kommunikation in Echtzeit erleichtert wird. Der Server definiert Methoden, die vom Client aufgerufen werden, und der Client definiert Methoden, die vom Server aufgerufen werden. SignalR ermöglicht auch eine indirekte Kommunikation von Client zu Client, die immer durch den SignalR Hub vermittelt wird, so dass Nachrichten zwischen einzelnen Clients, Gruppen oder an alle verbundenen Clients gesendet werden können. SignalR kümmert sich um alles, was erforderlich ist, um die Kommunikation zwischen Client und Server sowie zwischen Server und Client in Echtzeit zu ermöglichen.

Konfigurieren von SignalR-Hubs

Die SignalR-Middleware erfordert einige Dienste, die durch Aufrufe von AddSignalR konfiguriert werden:

services.AddSignalR();

Wenn Sie einer ASP.NET Core-App SignalR-Funktionen hinzufügen, richten Sie SignalR-Routen ein, indem Sie UseSignalR in der Startup.Configure-Methode aufrufen:

app.UseSignalR(route =>
{
    route.MapHub<ChatHub>("/chathub");
});

Erstellen und Verwenden von Hubs

Erstellen Sie einen Hub, indem Sie eine Klasse deklarieren, die von Hub erbt, und fügen Sie ihr öffentliche Methoden hinzu. Clients können Methoden aufrufen, die als public definiert sind:

public class ChatHub : Hub
{
    public Task SendMessage(string user, string message)
    {
        return Clients.All.SendAsync("ReceiveMessage", user, message);
    }
}

Sie können wie in jeder C#-Methode einen Rückgabetyp und Parameter angeben, auch komplexe Typen und Arrays. SignalR behandelt die Serialisierung und Deserialisierung komplexer Objekte und Arrays in Ihren Parametern und Rückgabewerten.

Das Context-Objekt

Die Hub-Klasse verfügt über eine Context-Eigenschaft, die die folgenden Eigenschaften mit Informationen zur Verbindung enthält:

Hub.Context enthält auch die folgenden Methoden:

Das Clients-Objekt

Die Hub-Klasse verfügt über eine Clients-Eigenschaft, die die folgenden Eigenschaften für die Kommunikation zwischen Server und Client enthält:

Hub.Clients enthält auch die folgenden Methoden:

Jede Eigenschaft oder Methode in den vorherigen Tabellen gibt ein Objekt mit einer SendAsync-Methode zurück. Mit der SendAsync-Methode können Sie den Namen und die Parameter der Clientmethode angeben, die aufgerufen werden soll.

Senden von Nachrichten an Clients

Verwenden Sie die Eigenschaften des Clients-Objekts, um Aufrufe für bestimmte Clients auszuführen. Im folgenden Beispiel gibt es drei Hubmethoden:

• SendMessage sendet mithilfe von Clients.All eine Nachricht an alle verbundenen Clients .
• SendMessageToCaller sendet mithilfe von Clients.Caller eine Nachricht zurück an den Aufrufer.
• SendMessageToGroup sendet eine Nachricht an alle Clients in der SignalR Users-Gruppe.

public Task SendMessage(string user, string message)
{
    return Clients.All.SendAsync("ReceiveMessage", user, message);
}

public Task SendMessageToCaller(string user, string message)
{
    return Clients.Caller.SendAsync("ReceiveMessage", user, message);
}

public Task SendMessageToGroup(string user, string message)
{
    return Clients.Group("SignalR Users").SendAsync("ReceiveMessage", user, message);
}

Stark typisierte Hubs

Ein Nachteil der Verwendung von SendAsync besteht darin, dass eine magische Zeichenfolge erforderlich ist, um die Clientmethode anzugeben, die aufgerufen werden soll. Dadurch kann es zu Laufzeitfehlern kommen, wenn der Methodenname falsch geschrieben ist oder im Client fehlt.

Eine Alternative zur Verwendung von SendAsync besteht darin, die Hub-Klasse mit Hub<T> stark zu typisieren. Im folgenden Beispiel wurden die ChatHub-Clientmethoden in eine Schnittstelle namens IChatClient extrahiert.

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

Diese Schnittstelle kann verwendet werden, um das vorherige ChatHub-Beispiel umzugestalten:

    public class StronglyTypedChatHub : Hub<IChatClient>
    {
        public async Task SendMessage(string user, string message)
        {
            await Clients.All.ReceiveMessage(user, message);
        }

        public Task SendMessageToCaller(string user, string message)
        {
            return Clients.Caller.ReceiveMessage(user, message);
        }
}

Die Verwendung von Hub<IChatClient> ermöglicht die Überprüfung der Clientmethoden zur Kompilierzeit. Dadurch werden Probleme verhindert, die durch die Verwendung von magischen Zeichenfolgen verursacht werden, weil Hub<T> nur Zugriff auf die in der Schnittstelle definierten Methoden bereitstellen kann.

Die Verwendung eines stark typisierten Hub<T> deaktiviert die Möglichkeit, SendAsync zu verwenden. Alle Methoden, die für die Schnittstelle definiert sind, können weiterhin als asynchron definiert werden. Tatsächlich sollte jede dieser Methoden einen Task zurückgeben. Da es sich um eine Schnittstelle handelt, verwenden Sie nicht das async-Schlüsselwort. Beispiel:

public interface IClient
{
    Task ClientMethod();
}

Ändern des Namens einer Hubmethode

Standardmäßig ist der Name einer Serverhubmethode der Name der .NET-Methode. Sie können jedoch das HubMethodName-Attribut verwenden, um diese Standardeinstellung zu ändern und manuell einen Namen für die Methode anzugeben. Der Client sollte diesen Namen anstelle des .NET-Methodennamens verwenden, wenn die Methode aufgerufen wird:

[HubMethodName("SendMessageToUser")]
public Task DirectMessage(string user, string message)
{
    return Clients.User(user).SendAsync("ReceiveMessage", user, message);
}

Behandeln von Ereignissen für eine Verbindung

Die Hubs-API von SignalR stellt die virtuellen OnConnectedAsync- und OnDisconnectedAsync-Methoden zum Verwalten und Nachverfolgen von Verbindungen bereit. Überschreiben Sie die virtuelle OnConnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client eine Verbindung mit dem Hub herstellt, ihn z. B. einer Gruppe hinzufügt:

public override async Task OnConnectedAsync()
{
    await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnConnectedAsync();
}

Überschreiben Sie die virtuelle OnDisconnectedAsync-Methode, um Aktionen auszuführen, wenn ein Client die Verbindung trennt. Wenn der Client die Verbindung absichtlich trennt (z. B. durch Aufrufen von connection.stop()), lautet der exception-Parameter null. Wenn der Client jedoch aufgrund eines Fehlers getrennt wird (z. B. durch einen Netzwerkfehler), enthält der exception-Parameter eine Ausnahme, die den Fehler beschreibt:

public override async Task OnDisconnectedAsync(Exception exception)
{
    await Clients.Group("SignalR Users").SendAsync("ReceiveMessage", "I", "disconnect");
    await base.OnDisconnectedAsync(exception);
}

RemoveFromGroupAsync muss nicht in OnDisconnectedAsync aufgerufen werden, das Element wird automatisch für Sie verarbeitet.

Umgang mit Fehlern

Ausnahmen, die in Ihren Hubmethoden ausgelöst werden, werden an den Client gesendet, der die Methode aufgerufen hat. Auf dem JavaScript-Client gibt die invoke-Methode eine JavaScript-Promise zurück. Wenn der Client einen Fehler mit einem an die Zusage angefügten Handler mit catch empfängt, wird er aufgerufen und als JavaScript-Error-Objekt übergeben:

connection.invoke("SendMessage", user, message).catch(err => console.error(err));

Wenn Ihr Hub eine Ausnahme auslöst, werden Verbindungen nicht geschlossen. SignalR gibt standardmäßig eine generische Fehlermeldung an den Client zurück. Beispiel:

Microsoft.AspNetCore.SignalR.HubException: An unexpected error occurred invoking 'MethodName' on the server.

Unerwartete Ausnahmen enthalten häufig vertrauliche Informationen, z. B. den Namen eines Datenbankservers in einer Ausnahme, die ausgelöst wird, wenn die Datenbankverbindung fehlschlägt. SignalR stellt diese detaillierten Fehlermeldungen als Sicherheitsmaßnahme standardmäßig nicht zur Verfügung. Weitere Informationen dazu, warum Ausnahmedetails unterdrückt werden, finden Sie unter Sicherheitsüberlegungen in ASP.NET Core SignalR.

Wenn Sie eine außergewöhnliche Bedingung haben, die Sie an den Client weitergeben möchten, können Sie die HubException-Klasse verwenden. Wenn Sie eine HubException aus Ihrer Hubmethode auslösen, sendetSignalR die gesamte Nachricht unverändert an den Client:

public Task ThrowException()
{
    throw new HubException("This error will be sent to the client!");
}

Zusätzliche Ressourcen

• Übersicht über ASP.NET CoreSignalR
• SignalR-JavaScript-Client in ASP.NET Core
• Veröffentlichen einer ASP.NET Core-SignalR-App bei Azure App Service