本章将和大家分享 ASP.NET Core SignalR 中的中心(服务端)。
本文大部分内容摘自微软官网:https://learn.microsoft.com/zh-cn/aspnet/core/signalr/hubs?view=aspnetcore-7.0
废话不多说,我们直接来看一个Demo,Demo的目录结构如下所示:
本Demo的Web项目为ASP.NET Core Web 应用程序(目标框架为.NET 7.0) MVC项目。
1、创建和使用中心
通过声明继承自 Hub 的类来创建中心。将方法添加到 public 类,使其可从客户端调用:
using Microsoft.AspNetCore.SignalR; namespace SignalRChat.Hubs { /// <summary> /// Hub 类管理连接、组和消息 /// </summary> public class ChatHub : Hub { /// <summary> /// 可通过已连接客户端调用 SendMessage,以向所有客户端发送消息 /// </summary> public async Task SendMessage(string user, string message) { //Clients.All 向所有的客户端发送消息(服务端调用客户端) //ReceiveMessage 是客户端监听的方法 await Clients.All.SendAsync("ReceiveMessage", user, message); /* // 常用方法 // 给所有人发送消息 await Clients.All.SendAsync("ReceiveMessage", data); // 给组里所有人发消息 await Clients.Group("Users").SendAsync("ReceiveMessage", data); // 给调用方法的那个人发消息 await Clients.Caller.SendAsync("ReceiveMessage", data); // 给除了调用方法的以外所有人发消息 await Clients.Others.SendAsync("ReceiveMessage", data); // 给指定connectionId的人发消息 await Clients.User(connectionId).SendAsync("ReceiveMessage", data); // 给指定connectionId的人发消息 await Clients.Client(connectionId).SendAsync("ReceiveMessage", data); // 给指定connectionId的人发消息,同时指定多个connectionId await Clients.Clients(IReadOnlyList<> connectionIds).SendAsync("ReceiveMessage", data); */ } } }
中心是暂时性的:
不要将状态存储在中心类的属性中。每个中心方法调用都在新的中心实例上执行。
请勿通过依赖项注入直接实例化中心。若要从应用程序中的其他位置向客户端发送消息,请使用 IHubContext 。
调用依赖于保持活动状态的中心的异步方法时请使用 await。例如,如果在没有 await 的情况下进行调用,则 Clients.All.SendAsync(...) 这类方法会失败,并且中心方法会在 SendAsync 完成之前完成。
2、配置 SignalR 中心
注册中心所需的 SignalR 服务 以及 配置SignalR终结点,修改 Program.cs 文件的代码,如下所示:
using SignalRChat.Hubs; namespace SignalRChat { public class Program { public static void Main(string[] args) { var builder = WebApplication.CreateBuilder(args); //服务注册(往容器中添加服务) // Add services to the container. builder.Services.AddControllersWithViews(); builder.Services.AddSignalR(); //注册中心所需的 SignalR 服务 var app = builder.Build(); //配置Http请求处理管道 // Configure the HTTP request pipeline. if (!app.Environment.IsDevelopment()) { app.UseExceptionHandler("/Home/Error"); } app.UseStaticFiles(); app.UseRouting(); app.UseAuthorization(); //配置MVC路由 app.MapControllerRoute( name: "areas", pattern: "{area:exists}/{controller=Home}/{action=Index}/{id?}"); app.MapControllerRoute( name: "default", pattern: "{controller=Home}/{action=Index}/{id?}"); //配置SignalR终结点 app.MapHub<ChatHub>("/chatHub"); //中心 app.MapHub<StronglyTypedChatHub>("/stronglyTypedChatHub"); //强类型中心 app.Run(); } } }
3、上下文对象
类 Hub 包含一个 Context 属性,该属性包含以下属性以及有关连接的信息:
属性 | 说明 |
ConnectionId | 获取连接的唯一 ID(由 SignalR 分配)。每个连接都有一个连接 ID。 |
UserIdentifier | 获取用户标识符。 默认情况下,SignalR 使用与连接关联的 ClaimsPrincipal 中的 ClaimTypes.NameIdentifier 作为用户标识符。 |
User | 获取与当前用户关联的 ClaimsPrincipal。 |
Items | 获取可用于在此连接范围内共享数据的键/值集合。数据可以存储在此集合中,会在不同的中心方法调用间为连接持久保存。 |
Features | 获取连接上可用的功能的集合。目前,在大多数情况下不需要此集合,因此未对其进行详细记录。 |
ConnectionAborted | 获取一个 CancellationToken,它会在连接中止时发出通知。 |
Hub.Context 还包含以下方法:
方法 | 说明 |
GetHttpContext | 获取 Http 请求的上下文对象,如果不是 Http 请求,则返回 null 。 |
Abort | 中止连接。 |
4、客户端对象
类 Hub 包含一个 Clients 属性,该属性包含以下属性,用于服务器和客户端之间的通信:
属性 | 说明 |
All | 对所有连接的客户端调用方法 |
Caller | 对调用了中心方法的客户端调用方法 |
Others | 对所有连接的客户端调用方法(调用了方法的客户端除外) |
Hub.Clients 还包含以下方法:
方法 | 说明 |
AllExcept | 对所有连接的客户端调用方法(指定连接除外) |
Client | 对连接的一个特定客户端调用方法 |
Clients | 对连接的多个特定客户端调用方法 |
Group | 对指定组中的所有连接调用方法 |
GroupExcept | 对指定组中的所有连接调用方法(指定连接除外) |
Groups | 对多个连接组调用方法 |
OthersInGroup | 对一个连接组调用方法(不包括调用了中心方法的客户端) |
User | 对与一个特定用户关联的所有连接调用方法 |
Users | 对与多个指定用户关联的所有连接调用方法 |
以上表中的每个属性或方法都返回具有 SendAsync 方法的对象。 方法 SendAsync 接收要调用的客户端方法的名称和任何参数。
5、向客户端发送消息
若要对特定客户端发出调用,请使用 Clients 对象的属性。 在以下示例中,有三种中心方法:
using Microsoft.AspNetCore.SignalR; namespace SignalRChat.Hubs { /// <summary> /// Hub 类管理连接、组和消息 /// </summary> public class ChatHub : Hub { /// <summary> /// 可通过已连接客户端调用 SendMessage,以向所有客户端发送消息 /// </summary> public async Task SendMessage(string user, string message) { //Clients.All 向所有的客户端发送消息(服务端调用客户端) //ReceiveMessage 是客户端监听的方法 await Clients.All.SendAsync("ReceiveMessage", user, message); //将消息发送到所有连接的客户端 /* // 常用方法 // 给所有人发送消息 await Clients.All.SendAsync("ReceiveMessage", data); // 给组里所有人发消息 await Clients.Group("Users").SendAsync("ReceiveMessage", data); // 给调用方法的那个人发消息 await Clients.Caller.SendAsync("ReceiveMessage", data); // 给除了调用方法的以外所有人发消息 await Clients.Others.SendAsync("ReceiveMessage", data); // 给指定connectionId的人发消息 await Clients.User(connectionId).SendAsync("ReceiveMessage", data); // 给指定connectionId的人发消息 await Clients.Client(connectionId).SendAsync("ReceiveMessage", data); // 给指定connectionId的人发消息,同时指定多个connectionId await Clients.Clients(IReadOnlyList<> connectionIds).SendAsync("ReceiveMessage", data); */ } 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); //将消息发送给 SignalR Users 组中的所有客户端 } }
6、强类型中心
使用 SendAsync 的缺点是它依赖于字符串来指定要调用的客户端方法。 如果客户端中的方法名称拼写错误或缺失,则这会使代码可能出现运行时错误。
使用 SendAsync 的另一种方法是使用 Hub<T>强类型Hub类。 在以下示例中 ChatHub ,客户端方法已提取到名为 的 IChatClient接口中:
namespace SignalRChat.Hubs { public interface IChatClient { /// <summary> /// 客户端方法 /// </summary> Task ReceiveMessage(string user, string message); } }
此接口可用于将前面的 ChatHub 示例重构为强类型:
using Microsoft.AspNetCore.SignalR; namespace SignalRChat.Hubs { /// <summary> /// 强类型中心 /// 中心是暂时性的:不要将状态存储在中心类的属性中。每个中心方法调用都在新的中心实例上执行。 /// </summary> public class StronglyTypedChatHub : Hub<IChatClient> { [HubMethodName("SendMessage")] //更改中心方法的名称 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); //将消息发送给 SignalR Users 组中的所有客户端 } }
使用 Hub<IChatClient> 可以对客户端方法进行编译时检查。 这可以防止使用字符串导致的问题,因为 Hub<T> 只能提供对 接口中定义的方法的访问。 使用强类型 Hub<T> 会禁止使用 SendAsync。
备注:Async后缀不会从方法名称中去除。 除非使用 .on('MyMethodAsync')定义客户端方法,否则不要使用 MyMethodAsync 作为名称。
7、更改中心方法的名称
默认情况下,服务器中心方法名称是 .NET 方法的名称。若要更改特定方法的此默认行为,请使用 HubMethodName 特性。调用方法时,客户端应使用此名称而不是 .NET 方法名称:
[HubMethodName("SendMessageToUser")] public async Task DirectMessage(string user, string message) => await Clients.User(user).SendAsync("ReceiveMessage", user, message);
8、将服务注入中心
中心构造函数可以接受 DI 中的服务作为参数,这些参数可以存储在类的属性中,以便在中心方法中使用。
为不同的中心方法注入多个服务或作为编写代码的替代方法时,中心方法也可以接受 DI 中的服务。 默认情况下,如果可能,将从 DI 检查和解析中心方法参数。
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); } }
如果不需要从服务隐式解析参数,请使用 DisableImplicitFromServicesParameters 禁用它。 若要在中心方法中显式指定从 DI 解析的参数,请使用 DisableImplicitFromServicesParameters 选项,并使用 [FromServices] 属性或自定义属性,该属性在应从 DI 解析的中心方法参数上实现 IFromServiceMetadata 。
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); } }
9、为连接处理事件
SignalR 中心 API 提供 OnConnectedAsync 和 OnDisconnectedAsync 虚方法来管理和跟踪连接。
/// <summary> /// 在客户端连接到中心时执行操作 /// </summary> /// <returns></returns> public override async Task OnConnectedAsync() { await Groups.AddToGroupAsync(Context.ConnectionId, "SignalR Users"); await base.OnConnectedAsync(); } /// <summary> /// 在客户端断开连接时执行操作 /// </summary> /// <param name="exception"></param> /// <returns></returns> public override async Task OnDisconnectedAsync(Exception? exception) { await base.OnDisconnectedAsync(exception); }
其中如果客户端有意断开连接(例如通过调用 connection.stop()),则 exception 参数为 null。但是,如果客户端由于错误(例如网络故障)而断开连接,则 exception 参数包含描述故障的异常。
RemoveFromGroupAsync 无需在 OnDisconnectedAsync 中调用,系统会自动处理它。
10、从中心外部发送消息
SignalR 中心是用于向连接到 SignalR 服务器的客户端发送消息的核心抽象。 你也可以使用 IHubContext 服务从应用中的其他位置发送消息。
备注:IHubContext 用于将通知发送到客户端,而非用于调用 Hub 上的方法。
1)获取 IHubContext 实例
在 ASP.NET Core SignalR 中,你可以通过依赖项注入来访问 IHubContext 实例。 你可以将 IHubContext 实例注入控制器、中间件或其他 DI 服务。 使用该实例向客户端发送消息。
2)在控制器中注入 IHubContext 实例
通过将 IHubContext 实例添加到构造函数,可以将其注入控制器:
public class HomeController : Controller { private readonly IHubContext<NotificationHub> _hubContext; public HomeController(IHubContext<NotificationHub> hubContext) { _hubContext = hubContext; } }
获权访问 IHubContext 实例后,就像在中心本身一样调用客户端方法:
public async Task<IActionResult> Index() { await _hubContext.Clients.All.SendAsync("Notify", $"Home page loaded at: {DateTime.Now}"); return View(); }
3)在中间件中获取 IHubContext 实例
访问中间件管道中的 IHubContext,如下所示:
app.Use(async (context, next) => { var hubContext = context.RequestServices .GetRequiredService<IHubContext<ChatHub>>(); //... if (next != null) { await next.Invoke(); } });
备注:当从 Hub 类外部调用客户端方法时,没有与该调用关联的调用方。 因此,无法访问 ConnectionId、Caller 和 Others 属性。
4)从 IHost 获取 IHubContext 实例
从 Web 主机访问 IHubContext 对于与 ASP.NET Core 之外的区域集成很有用,例如,使用第三方依赖项注入框架:
public class Program { public static void Main(string[] args) { var host = CreateHostBuilder(args).Build(); var hubContext = host.Services.GetService(typeof(IHubContext<ChatHub>)); host.Run(); } public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args) .ConfigureWebHostDefaults(webBuilder => { webBuilder.UseStartup<Startup>(); }); }
5)注入强类型 HubContext
若要注入强类型 HubContext,请确保中心继承自 Hub<T>。 使用 IHubContext<THub, T> 接口而不是 IHubContext<THub> 进行注入。
public class ChatController : Controller { public IHubContext<ChatHub, IChatClient> _strongChatHubContext { get; } public ChatController(IHubContext<ChatHub, IChatClient> chatHubContext) { _strongChatHubContext = chatHubContext; } public async Task SendMessage(string user, string message) { await _strongChatHubContext.Clients.All.ReceiveMessage(user, message); } }
6)在泛型代码中使用 IHubContext
注入的 IHubContext<THub> 实例可以强制转换为 IHubContext,而无需指定泛型 Hub 类型。
class MyHub : Hub { } class MyOtherHub : Hub { } app.Use(async (context, next) => { var myHubContext = context.RequestServices .GetRequiredService<IHubContext<MyHub>>(); var myOtherHubContext = context.RequestServices .GetRequiredService<IHubContext<MyOtherHub>>(); await CommonHubContextMethod((IHubContext)myHubContext); await CommonHubContextMethod((IHubContext)myOtherHubContext); await next.Invoke(); } async Task CommonHubContextMethod(IHubContext context) { await context.Clients.All.SendAsync("clientMethod", new Args()); }
此操作在以下情况下十分有用:
- 编写不引用应用正在使用的特定 Hub 类型的库。
- 编写可应用于多个不同 Hub 实现的泛型代码。
11、管理 SignalR 中的用户和组
SignalR 允许将消息发送到与特定用户关联的所有连接,以及指定的连接组。
1)SignalR 中的用户
SignalR 中的单个用户可以与一个应用建立多个连接。 例如,用户可以在桌面和手机上进行连接。 每台设备都有一个单独的 SignalR 连接,但它们都与同一个用户关联。 如果向用户发送消息,则与该用户关联的所有连接都会收到消息。 可以通过中心内的 Context.UserIdentifier 属性访问连接的用户标识符。
默认情况下,SignalR 使用与连接关联的 ClaimsPrincipal 中的 ClaimTypes.NameIdentifier 作为用户标识符。 若要自定义此行为,请参阅使用声明自定义标识处理。
通过将用户标识符传递给中心方法中的 User 函数,向特定用户发送消息,如以下示例所示:
public Task SendPrivateMessage(string user, string message) { return Clients.User(user).SendAsync("ReceiveMessage", message); }
备注:用户标识符区分大小写。
2)SignalR 中的组
组是与名称关联的连接集合。你可以将消息发送到组中的所有连接。建议通过组发送到一个或多个连接,因为组由应用程序管理。一个连接可以是多个组的成员。组非常适合聊天应用程序之类的应用,其中每个聊天室都可以表示为一个组。可通过 AddToGroupAsync 和 RemoveFromGroupAsync 方法在组中添加或删除连接。
public async Task AddToGroup(string groupName) { await Groups.AddToGroupAsync(Context.ConnectionId, groupName); await Clients.Group(groupName).SendAsync("Send", $"{Context.ConnectionId} has joined the group {groupName}."); } public async Task RemoveFromGroup(string groupName) { await Groups.RemoveFromGroupAsync(Context.ConnectionId, groupName); await Clients.Group(groupName).SendAsync("Send", $"{Context.ConnectionId} has left the group {groupName}."); }
重新连接时不会保留组成员身份。重新建立连接后,需要重新加入组。无法计算组的成员数,因为如果将应用程序扩展到多台服务器,则无法获取此信息。
若要在使用组时保护对资源的访问,请使用 ASP.NET Core 中的身份验证和授权功能。如果仅当凭据对组有效时才将用户添加到该组,则发送到该组的消息将仅发送给授权用户。但是,组不是一项安全功能。身份验证声明具有组不具备的功能,例如到期和撤销。如果撤销用户对组的访问权限,应用必须从组中显式删除该用户。
备注:组名称区分大小写。
12、SignalR API 设计注意事项
使用自定义对象参数确保向后兼容性
将新的参数添加到 SignalR 客户端或服务器上的中心方法是一项重大更改。这意味着,较旧的客户端/服务器在尝试调用没有适当数量参数的方法时会出错。但是,向自定义对象参数添加属性不是一项中断性变更。这可用于设计兼容的 API,以适应客户端或服务器上的更改。
使用自定义对象作为参数可提供更大的灵活性,如下所示:
public class TotalLengthRequest { public string Param1 { get; set; } public string Param2 { get; set; } } public async Task GetTotalLength(TotalLengthRequest req) { var length = req.Param1.Length; if (req.Param2 != null) { length += req.Param2.Length; } return length; }
当旧客户端发送单个参数时,额外的 Param2
属性将保留为 null
。 你可以通过检查 Param2
是否为 null
来检测旧客户端发送的消息并应用默认值。 新客户端可以发送这两个参数。
connection.invoke("GetTotalLength", { param1: "value1", param2: "value2" });
此技术同样适用于客户端上定义的方法。 你可以从服务器端发送自定义对象:
public async Task Broadcast(string message) { await Clients.All.SendAsync("ReceiveMessage", new { Sender = Context.User.Identity.Name, Message = message }); }
旧客户端不需要 Sender
值,因此会忽略它。 新客户端可以通过更新为读取新属性来接受它:
connection.on("ReceiveMessage", (req) => { let message = req.message; if (req.sender) { message = req.sender + ": " + message; } appendMessageToChatWindow(message); });
在这种情况下,新客户端也可以容忍不提供 Sender
值的旧服务器。由于旧服务器不提供 Sender
值,因此客户端在访问它之前会检查它是否存在。
Demo源码:
链接:https://pan.baidu.com/s/1AbGaPRfv2vAskHRAnOlvYA 提取码:456q
此文由博主精心撰写转载请保留此原文链接:https://www.cnblogs.com/xyh9039/p/17536693.html文章来源:https://www.toymoban.com/news/detail-533740.html
版权声明:如有雷同纯属巧合,如有侵权请及时联系本人修改,谢谢!!!文章来源地址https://www.toymoban.com/news/detail-533740.html
到了这里,关于ASP.NET Core SignalR 系列(二)- 中心(服务端)的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!