作者： Rachel Appel和古柯 Griffin

查看或下载示例代码 （如何下载）

什么是 SignalR 中心

利用 SignalR 集线器 API，你可以从服务器对连接的客户端调用方法。 在服务器代码中，您将定义由客户端调用的方法。 在客户端代码中，您将定义从服务器调用的方法。 SignalR 负责使实时的客户端到服务器和服务器到客户端的通信成为可能。

配置 SignalR 集线器

SignalR 中间件需要一些服务，这些服务通过调用 services.AddSignalR进行配置。

services.AddSignalR();

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

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

创建和使用集线器

通过声明从Hub继承的类来创建中心，并向其添加公共方法。 客户端可以调用定义为public的方法。

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

您可以指定返回类型和参数（包括复杂类型和数组），就像在任何C#方法中一样。 SignalR 处理参数和返回值中的复杂对象和数组的序列化和反序列化。

上下文对象

Hub 类具有一个 Context 属性，其中包含有关连接的信息的以下属性：

Hub.Context 还包含以下方法：

Clients 对象

Hub 类具有一个 Clients 属性，其中包含服务器和客户端之间的通信的以下属性：

Hub.Clients 还包含以下方法：

上表中的每个属性或方法返回一个具有 SendAsync 方法的对象。 利用 SendAsync 方法，你可以提供要调用的客户端方法的名称和参数。

向客户端发送消息

若要调用特定客户端，请使用 Clients 对象的属性。 在下面的示例中，有三种集线器方法：

• SendMessage 使用 Clients.All将消息发送到所有连接的客户端。
• SendMessageToCaller 使用 Clients.Caller将消息发送回调用方。
• SendMessageToGroups 向 SignalR Users 组中的所有客户端发送一条消息。

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

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

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

强类型中心

使用 SendAsync 的缺点是它依赖于幻字符串来指定要调用的客户端方法。 如果客户端中的方法名称拼写错误或缺失，则这会使代码对运行时错误开放。

使用 SendAsync 的一种替代方法是使用 Hub<T>强键入 Hub。 在下面的示例中，已将 ChatHub 客户端方法提取到名为 IChatClient的接口。

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

此接口可用于重构前面的 ChatHub 示例。

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

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

使用 Hub<IChatClient> 启用对客户端方法的编译时检查。 这可以防止由于使用神奇字符串而导致的问题，因为 Hub<T> 只能提供对在接口中定义的方法的访问。

使用强类型 Hub<T> 禁用使用 SendAsync的能力。 接口上定义的任何方法仍可以定义为异步方法。 事实上，其中每个方法都应该返回 Task。 由于它是一个接口，因此请勿使用 async 关键字。 例如：

public interface IClient
{
    Task ClientMethod();
}

更改集线器方法的名称

默认情况下，服务器集线器方法名称是 .NET 方法的名称。 但是，可以使用HubMethodName属性来更改此默认设置，并手动指定方法的名称。 调用方法时，客户端应使用此名称，而不是 .NET 方法名称。

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

处理连接事件

SignalR 中心 API 提供 OnConnectedAsync 和 OnDisconnectedAsync 虚拟方法来管理和跟踪连接。 重写 OnConnectedAsync 虚方法，以便在客户端连接到集线器时执行操作，如将其添加到组中。

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

重写 OnDisconnectedAsync 虚方法，以便在客户端断开连接时执行操作。 如果客户端故意断开连接（例如，通过调用 connection.stop()），exception 参数将 null。 但是，如果客户端由于错误（例如网络故障）而断开连接，则 exception 参数将包含描述失败的异常。

public override async Task OnDisconnectedAsync(Exception exception)
{
    await Groups.RemoveFromGroupAsync(Context.ConnectionId, "SignalR Users");
    await base.OnDisconnectedAsync(exception);
}

处理错误

在中心方法中引发的异常将发送到调用方法的客户端。 在 JavaScript 客户端上，invoke 方法返回Javascript 承诺。 当客户端使用 catch收到包含附加到承诺的处理程序的错误时，将调用该处理程序并将其作为 JavaScript Error 对象进行传递。

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

如果中心引发异常，则不会关闭连接。 默认情况下，SignalR 会向客户端返回一般的错误消息。 例如：

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

意外的异常通常包含敏感信息，例如数据库连接失败时触发的异常中的数据库服务器的名称。 默认情况下，SignalR 不会公开这些详细的错误消息作为一种安全措施。 有关抑制异常详细信息的原因的详细信息，请参阅安全注意事项一文。

如果要将异常情况传播到客户端，则可以使用 HubException 类。 如果从中心方法引发 HubException，SignalR会将整个消息发送到客户端（未修改）。

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

相关资源

• ASP.NET Core 的简介 SignalR
• JavaScript 客户端
• 发布到 Azure