diff --git a/docs/en/Samples/Index.md b/docs/en/Samples/Index.md index 12095bb2c9..b5fae6cbce 100644 --- a/docs/en/Samples/Index.md +++ b/docs/en/Samples/Index.md @@ -37,7 +37,7 @@ While there is no Razor Pages & MongoDB combination, you can check both document * [EF Core database migrations document](../Entity-Framework-Core-Migrations.md) * **SignalR Demo**: A simple chat application that allows to send and receive messages among authenticated users. * [Source code](https://github.com/abpframework/abp-samples/tree/master/SignalRDemo) - * [Signal Integration document](../SignalR-Integration.md) + * [SignalR Integration document](../SignalR-Integration.md) * **Dashboard Demo**: A simple application to show how to use the widget system for the ASP.NET Core MVC UI. * [Source code](https://github.com/abpframework/abp-samples/tree/master/DashboardDemo) * [Widget documentation](../UI/AspNetCore/Widgets.md) diff --git a/docs/en/SignalR-Integration.md b/docs/en/SignalR-Integration.md index 415b585f3f..0a2ebdaa54 100644 --- a/docs/en/SignalR-Integration.md +++ b/docs/en/SignalR-Integration.md @@ -25,7 +25,7 @@ If you want to manually install; 1. Add the [Volo.Abp.AspNetCore.SignalR](https://www.nuget.org/packages/Volo.Abp.AspNetCore.SignalR) NuGet package to your project: ``` - Install-Package Volo.Abp.BackgroundJobs.HangFire + Install-Package Volo.Abp.AspNetCore.SignalR ``` Or use the Visual Studio NuGet package management UI to install it. diff --git a/docs/zh-Hans/Samples/Index.md b/docs/zh-Hans/Samples/Index.md index 774d6467ef..97569f2ae2 100644 --- a/docs/zh-Hans/Samples/Index.md +++ b/docs/zh-Hans/Samples/Index.md @@ -35,6 +35,9 @@ * **Entity Framework 迁移**: 演示如何将应用程序拆分为多个数据库的解决方案. 每个数据库包含不同的模块. * [源码](https://github.com/abpframework/abp-samples/tree/master/DashboardDemo) * [EF Core数据库迁移文档](../Entity-Framework-Core-Migrations.md) +* **SignalR Demo**: A simple chat application that allows to send and receive messages among authenticated users. + * [源码](https://github.com/abpframework/abp-samples/tree/master/SignalRDemo) + * [SignalR 集成文档](../SignalR-Integration.md) * **Dashboard Demo**: 一个简单的应用程序,展示了如何在ASP.NET Core MVC UI中使用widget系统. * [源码](https://github.com/abpframework/abp-samples/tree/master/DashboardDemo) * [Widget 文档](../UI/AspNetCore/Widgets.md) diff --git a/docs/zh-Hans/SignalR-Integration.md b/docs/zh-Hans/SignalR-Integration.md new file mode 100644 index 0000000000..8045bbd394 --- /dev/null +++ b/docs/zh-Hans/SignalR-Integration.md @@ -0,0 +1,227 @@ +# SignalR 集成 + +> 你可以按照[标准的微软教程](https://docs.microsoft.com/en-us/aspnet/core/tutorials/signal)添加[SignalR](https://docs.microsoft.com/en-us/aspnet/core/signalr/introduction)到你的应用程序,但ABP提供了简化集成的SignalR集成包. + +## 安装 + +### 服务器端 + +建议使用[ABP CLI](CLI.md)安装包. + +#### 使用 ABP CLI + +在项目的文件夹(.csproj文件)中打开命令行窗口,然后输入以下命令: + +```bash +abp add-package Volo.Abp.AspNetCore.SignalR +``` + +> 你通常需要将此软件包添加到应用程序的Web或API层,具体取决于你的架构. + +#### 手动安装 + +如果你想手动安装: + +1. 添加[Volo.Abp.AspNetCore.SignalR](https://www.nuget.org/packages/Volo.Abp.AspNetCore.SignalR)NuGet包到你的项目: + + ``` + Install-Package Volo.Abp.AspNetCore.SignalR + ``` + + 或者使用VisualStudio提供的UI安装 + +2. 添加 `AbpAspNetCoreSignalRModule` 到你的模块的依赖列表. + +```csharp +[DependsOn( + //...other dependencies + typeof(AbpAspNetCoreSignalRModule) //Add the new module dependency + )] +public class YourModule : AbpModule +{ +} +``` + +> 你不需要 `services.AddSignalR()` 和 `app.UseEndpoints(...)`,它们在 `AbpAspNetCoreSignalRModule` 中已经添加了. + +### 客户端 + +客户端安装取决于你的UI框架/客户端类型. + +#### ASP.NET Core MVC / Razor Pages UI + +在你的Web项目的根文件夹中运行以下命令: + +````bash +yarn add @abp/signalr +```` + +> 需要 [yarn](https://yarnpkg.com/) 环境. + +它会添加 `@abp/signalr` 到你的项目中的 `package.json` 依赖项: + +````json +{ + ... + "dependencies": { + ... + "@abp/signalr": "~2.7.0" + } +} +```` + +在你的Web项目的根文件夹中运行 `gulp`: + +````bash +gulp +```` + +它会将SignalR JavaScript文件拷贝到你的项目: + +![signal-js-file](images/signal-js-file.png) + +最后将以下代码添加到页面/视图中, 添加包含 `signalr.js` 文件: + +````xml +@section scripts { + +} +```` + +它需要将 `@using Volo.Abp.AspNetCore.Mvc.UI.Packages.SignalR` 添加到你的页面/视图. + +> 你可以用标准方式添加 `signalr.js` 文件. 但是使用 `SignalRBrowserScriptContributor` 具有其他好处. 有关详细信息,请参见[客户端程序包管理](UI/AspNetCore/Client-Side-Package-Management.md)和[捆绑和压缩文档](UI/AspNetCore/Bundling-Minification.md). + +这就是全部了,你可以在你的页面使用[SignalR JavaScript API](https://docs.microsoft.com/en-us/aspnet/core/signalr/javascript-client). + +#### 其他的UI框架/客户端 + +其他类型的客户端请参考[微软文档](https://docs.microsoft.com/en-us/aspnet/core/signalr/introduction). + +## ABP框架集成 + +本节介绍了使用ABP框架集成包的其他好处. + +### Hub 路由与Mapping + +ABP自动将所有集线器注册到[依赖注入](Dependency-Injection.md)(做为transient)并映射集线器端点. 因此你不需要使用 `app.UseEndpoints(...)` 即可映射你的集线器.集线器路由(URL)通常是根据你的集线器名称确定. + +示例: + +````csharp +public class MessagingHub : Hub +{ + //... +} +```` + +`MessasingHub` 集线器的路由为 `/signalr-hubs/messasing`: + +* 添加了标准 `/signalr-hubs/` 前缀. +* 使用**驼峰命名**集线器名称,不包含 `Hub` 后缀. + +如果你想指定路由,你可以使用 `HubRoute` attribute: + +````csharp +[HubRoute("/my-messasing-hub")] +public class MessagingHub : Hub +{ + //... +} +```` + +### AbpHub 基类 + +你可以从 `AbpHub` 或 `AbpHub` 继承标准的 `Hub` 和 `Hub` 类,它们具有实用的基本属性,如 `CurrentUser`. + +示例: + +````csharp +public class MessagingHub : AbpHub +{ + public async Task SendMessage(string targetUserName, string message) + { + var currentUserName = CurrentUser.UserName; //Access to the current user info + var txt = L["MyText"]; //Localization + } +} +```` + +> 虽然可以将相同的属性注入到集线器构造函数中,但是这种方式简化了集线器类. + +### 手动注册/Mapping + +ABP会自动将所有集线器注册到[依赖注入](Dependency-Injection.md)作为**transient service**. 如果想要禁用集线器类**自动添加依赖注入**,只需要使用 `DisableConventionalRegistration` attribute. 如果愿意,你仍然可以在模块的 `ConfigureServices` 方法中注册集线器类: + +````csharp +context.Services.AddTransient(); +```` + +当**你或ABP**将类注册到依赖注入时,如前几节所述,它会自动映射到端点路由配置. 如果要手动映射集线器类,你可以使用 `DisableAutoHubMap` attribute. + +对于手动映射,你有两个选择: + +1. 使用 `AbpSignalROptions` 添加map配置(在[模块](Module-Development-Basics.md)的 `ConfigureServices` 方法中),ABP会为集线器执行端点映射: + +````csharp +Configure(options => +{ + options.Hubs.Add( + new HubConfig( + typeof(MessagingHub), //Hub type + "/my-messaging/route", //Hub route (URL) + hubOptions => + { + //Additional options + hubOptions.LongPolling.PollTimeout = TimeSpan.FromSeconds(30); + } + ) + ); +}); +```` + +这是提供其他SignalR选项的好方式. + +如果你不想禁用自动集线器map,但仍想执行其他SignalR配置,可以使用 `options.Hubs.AddOrUpdate(...)` 方法: + +````csharp +Configure(options => +{ + options.Hubs.AddOrUpdate( + typeof(MessagingHub), //Hub type + config => //Additional configuration + { + config.RoutePattern = "/my-messaging-hub"; //override the default route + config.ConfigureActions.Add(hubOptions => + { + //Additional options + hubOptions.LongPolling.PollTimeout = TimeSpan.FromSeconds(30); + }); + } + ); +}); +```` + +你可以通过这种方式修改在依赖模块(没有源代码访问权限)中定义的集线器类的选项. + +2. 在[模块](Module-Development-Basics.md)的 `OnApplicationInitialization` 方法中更改 `app.UseConfiguredEndpoints`(添加了lambda方法作为参数). + +````csharp +app.UseConfiguredEndpoints(endpoints => +{ + endpoints.MapHub("/my-messaging-hub", options => + { + options.LongPolling.PollTimeout = TimeSpan.FromSeconds(30); + }); +}); +```` + +### UserIdProvider + +ABP实现 `SignalR` 的 `IUserIdProvider` 接口,从ABP框架的 `ICurrentUser` 服务提供当前用户ID(请参阅[当前用户服务](CurrentUser.md)),它将集成到应用程序的身份验证系统中,实现类是 `AbpSignalRUserIdProvider` (如果你想更改/覆盖它). + +## 示例应用程序 + +参阅 [SignalR集成Demo](https://github.com/abpframework/abp-samples/tree/master/SignalRDemo),它有一个简单的聊天页面,可以在(经过身份验证的)用户之间发送消息. + +![signalr-demo-chat](images/signalr-demo-chat.png) \ No newline at end of file diff --git a/docs/zh-Hans/images/signal-js-file.png b/docs/zh-Hans/images/signal-js-file.png new file mode 100644 index 0000000000..19fc6cefe3 Binary files /dev/null and b/docs/zh-Hans/images/signal-js-file.png differ diff --git a/docs/zh-Hans/images/signalr-demo-chat.png b/docs/zh-Hans/images/signalr-demo-chat.png new file mode 100644 index 0000000000..120d7eda6e Binary files /dev/null and b/docs/zh-Hans/images/signalr-demo-chat.png differ