教程：使用 TypeScript 和 Webpack 开始使用 ASP.NET Core SignalR

作者：Sébastien Sougnez

本教程演示如何在 ASP.NET Core SignalR Web 应用中使用 Webpack 来捆绑和构建用 TypeScript 编写的客户端。 开发人员可以通过 Webpack 捆绑和生成 Web 应用的客户端资源。

在本教程中，你将了解如何执行以下操作：

• 创建 ASP.NET Core SignalR 应用
• 配置 SignalR 服务器
• 使用 Webpack 配置生成管道
• 配置 SignalR TypeScript 客户端
• 启用客户端和服务器之间的通信

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

先决条件

• 带 npm 的 Node.js

Visual Studio

• 带有 ASP.NET 和 Web 开发工作负载的 Visual Studio 2022。

  

Visual Studio Code

• Visual Studio Code
• 用于 Visual Studio Code 的 C#（最新版本）
• .NET 8.0 SDK

Visual Studio Code 说明使用用于 ASP.NET Core 的 .NET CLI 开发功能，如项目创建。 可在（macOS、Linux 或 Windows）上或在任何代码编辑器中遵循这些说明。 如果使用 Visual Studio Code 以外的其他内容，则可能需要进行少量更改。

创建 ASP.NET Core Web 应用

Visual Studio

默认情况下，Visual Studio 使用在安装目录中找到的 npm 版本。 配置 Visual Studio，在 PATH 环境变量中查找 npm：

启动 Visual Studio。 在“启动”窗口中，选择“继续但无需代码”。

1. 导航到“工具”>“选项”>“项目和解决方案”>“Web 包管理”>“外部 Web 工具”。

2. 在列表中选择 $(PATH) 项。 选择向上键将项移动列表中的第二个位置，然后选择“确定”：

   。

新建 ASP.NET Core Web 应用：

1. 使用“文件”>“新建”>“项目”菜单选项，然后选择“ASP.NET Core 空”模板。 选择“下一页”。
2. 将项目命名为 SignalRWebpack 并选择“创建”。
3. 从“框架”下拉列表中选择“.NET 8.0(长期支持)”。 选择创建。

将 Microsoft.TypeScript.MSBuild NuGet 包添加到项目：

1. 在“解决方案资源管理器”中，右键单击项目节点，然后选择“管理 NuGet 包”。 在“浏览”选项卡中，搜索 Microsoft.TypeScript.MSBuild，然后选择右侧的“安装”来安装包。

Visual Studio 会将 NuGet 包添加到解决方案资源管理器中的“依赖项”节点下，从而在项目中启用 TypeScript 编译 。

Visual Studio Code

在“集成终端”中运行以下命令：

dotnet new web -o SignalRWebpack
code -r SignalRWebpack

• dotnet new 命令会在 SignalRWebpack 目录中创建一个空的 ASP.NET Core Web 应用。
• code 命令会在 Visual Studio Code 的当前实例中打开 SignalRWebpack 目录。

Visual Studio Code 可能会显示一个对话框，询问：“你是否信任此文件夹中的文件作者?”

• 如果你信任父文件夹中的所有文件，请选择“信任父文件夹中所有文件的作者”。
• 选择“是，我信任所有作者”，因为项目文件夹包含 .NET 生成的文件。
• 当 Visual Studio Code 请求你添加资产来生成和调试项目时，请选择“是”。 如果 Visual Studio Code 不提供添加生成和调试资产的功能，请选择“视图”>“命令面板”，然后在搜索框中输入“.NET”。 从命令列表中选择 .NET: Generate Assets for Build and Debug 命令。

Visual Studio Code 添加一个包含生成的 launch.json 和 tasks.json 文件的 .vscode 文件夹。

在“集成终端”中运行以下 .NET CLI 命令：

dotnet add package Microsoft.TypeScript.MSBuild

上述命令将添加 Microsoft.TypeScript.MSBuild 包，从而在项目中启用 TypeScript 编译。

配置服务器

在本部分，配置 ASP.NET Core Web 应用以发送和接收 SignalR 消息。

1. 在 Program.cs 中，调用 AddSignalR：

   var builder = WebApplication.CreateBuilder(args);
   
   builder.Services.AddSignalR();
   

2. 同样，在 Program.cs 中，调用 UseDefaultFiles 和 UseStaticFiles：

   var app = builder.Build();
   
   app.UseDefaultFiles();
   app.UseStaticFiles();
   

   上述代码允许服务器查找和处理 index.html 文件。 无论用户输入完整 URL 还是 Web 应用的根 URL，都会提供该文件。

3. 在项目根目录 SignalRWebpack/ 中，为 SignalR类创建名为 Hubs 的新目录。

4. 创建包含以下代码的新文件 Hubs/ChatHub.cs：

   using Microsoft.AspNetCore.SignalR;
   
   namespace SignalRWebpack.Hubs;
   
   public class ChatHub : Hub
   {
       public async Task NewMessage(long username, string message) =>
           await Clients.All.SendAsync("messageReceived", username, message);
   }
   

   服务器收到消息后，前面的代码会将这些消息播发到所有连接的用户。 没有必要使用泛型 on 方法接收所有消息。 使用以消息名称命名的方法就可以了。

   在此示例中：

   • TypeScript 客户端发送一条标识为 newMessage 的消息。
   • C# NewMessage 方法需要客户端发送的数据。
   • 在 Clients.All 上对 SendAsync 进行调用。
   • 接收的消息会发送到所有连接到中心的客户端。

5. 在 Program.cs 顶部添加以下 using 语句来解析 ChatHub 引用：

   using SignalRWebpack.Hubs;
   

6. 在 Program.cs 中，将 /hub 路由映射到 ChatHub 中心。 将显示 Hello World! 的代码替换为以下代码：

   app.MapHub<ChatHub>("/hub");
   

配置客户端

在本部分，创建一个 Node.js 项目，以使用 Webpack 将 TypeScript 转换为 JavaScript 并捆绑客户端资源，包括 HTML 和 CSS。

1. 在项目根目录中运行以下命令，创建 package.json 文件：

   npm init -y
   

2. 将突出显示的属性添加到 package.json 文件并保存文件更改：

   {
     "name": "SignalRWebpack",
     "version": "1.0.0",
     "private": true,
     "description": "",
     "main": "index.js",
     "scripts": {
       "test": "echo \"Error: no test specified\" && exit 1"
     },
     "keywords": [],
     "author": "",
     "license": "ISC"
   }
   

   将 private 属性设置为 true，防止下一步出现包安装警告。

3. 安装所需的 npm 包。 从项目根目录运行以下命令：

   npm i -D -E clean-webpack-plugin css-loader html-webpack-plugin mini-css-extract-plugin ts-loader typescript webpack webpack-cli
   

   -E 选项禁用 npm 将语义化版本控制范围运算符写到 package.json 的默认行为。 例如，使用 "webpack": "5.76.1" 而不是 "webpack": "^5.76.1"。 此选项防止意外升级到新的包版本。

   有关详细信息，请参阅 npm-install 文档。

4. 将 package.json 文件的 scripts 属性替换为以下代码：

   "scripts": {
     "build": "webpack --mode=development --watch",
     "release": "webpack --mode=production",
     "publish": "npm run release && dotnet publish -c Release"
   },
   

   定义以下脚本：

   • build：在开发模式下捆绑客户端资源并观察文件更改。 文件观察程序使捆绑在每次项目文件发生更改时重新生成。 mode 选项可禁用生产优化，例如摇树优化和缩小优化。 仅在开发中使用 build。
   • release：在生产模式下捆绑客户端资源。
   • publish：运行 release 脚本，在生产模式下捆绑客户端资源。 它调用 .NET CLI 的 publish 命令发布应用。

5. 在项目根目录中创建名为 webpack.config.js 的文件，使其包含以下代码：

   const path = require("path");
   const HtmlWebpackPlugin = require("html-webpack-plugin");
   const { CleanWebpackPlugin } = require("clean-webpack-plugin");
   const MiniCssExtractPlugin = require("mini-css-extract-plugin");
   
   module.exports = {
       entry: "./src/index.ts",
       output: {
           path: path.resolve(__dirname, "wwwroot"),
           filename: "[name].[chunkhash].js",
           publicPath: "/",
       },
       resolve: {
           extensions: [".js", ".ts"],
       },
       module: {
           rules: [
               {
                   test: /\.ts$/,
                   use: "ts-loader",
               },
               {
                   test: /\.css$/,
                   use: [MiniCssExtractPlugin.loader, "css-loader"],
               },
           ],
       },
       plugins: [
           new CleanWebpackPlugin(),
           new HtmlWebpackPlugin({
               template: "./src/index.html",
           }),
           new MiniCssExtractPlugin({
               filename: "css/[name].[chunkhash].css",
           }),
       ],
   };
   

   前面的文件配置 Webpack 编译过程：

   • output 属性替代 dist 的默认值。 捆绑反而在 wwwroot 目录中发出。
   • resolve.extensions 数组包含 .js，以便导入 SignalR 客户端 JavaScript。

6. 在项目根目录 SignalRWebpack/ 中，为客户端代码创建名为 src 的新目录。

7. 将 src 目录及其内容从示例项目复制到项目根目录中。 src 包含以下文件：

   • index.html，用于定义主页的样板标记：

     <!DOCTYPE html>
     <html lang="en">
       <head>
         <meta charset="utf-8" />
         <title>ASP.NET Core SignalR with TypeScript and Webpack</title>
       </head>
       <body>
         <div id="divMessages" class="messages"></div>
         <div class="input-zone">
           <label id="lblMessage" for="tbMessage">Message:</label>
           <input id="tbMessage" class="input-zone-input" type="text" />
           <button id="btnSend">Send</button>
         </div>
       </body>
     </html>
     

   • css/main.css，用于为主页提供 CSS 样式：

     *,
     *::before,
     *::after {
       box-sizing: border-box;
     }
     
     html,
     body {
       margin: 0;
       padding: 0;
     }
     
     .input-zone {
       align-items: center;
       display: flex;
       flex-direction: row;
       margin: 10px;
     }
     
     .input-zone-input {
       flex: 1;
       margin-right: 10px;
     }
     
     .message-author {
       font-weight: bold;
     }
     
     .messages {
       border: 1px solid #000;
       margin: 10px;
       max-height: 300px;
       min-height: 300px;
       overflow-y: auto;
       padding: 5px;
     }
     

   • tsconfig.json，用于配置 TypeScript 编译器以生成与 ECMAScript 5 兼容的 JavaScript：

     {
       "compilerOptions": {
         "target": "es5"
       }
     }
     

   • index.ts：

     import * as signalR from "@microsoft/signalr";
     import "./css/main.css";
     
     const divMessages: HTMLDivElement = document.querySelector("#divMessages");
     const tbMessage: HTMLInputElement = document.querySelector("#tbMessage");
     const btnSend: HTMLButtonElement = document.querySelector("#btnSend");
     const username = new Date().getTime();
     
     const connection = new signalR.HubConnectionBuilder()
         .withUrl("/hub")
         .build();
     
     connection.on("messageReceived", (username: string, message: string) => {
       const m = document.createElement("div");
     
       m.innerHTML = `<div class="message-author">${username}</div><div>${message}</div>`;
     
       divMessages.appendChild(m);
       divMessages.scrollTop = divMessages.scrollHeight;
     });
     
     connection.start().catch((err) => document.write(err));
     
     tbMessage.addEventListener("keyup", (e: KeyboardEvent) => {
       if (e.key === "Enter") {
         send();
       }
     });
     
     btnSend.addEventListener("click", send);
     
     function send() {
       connection.send("newMessage", username, tbMessage.value)
         .then(() => (tbMessage.value = ""));
     }
     

     前面的代码检索对 DOM 元素的引用并附加两个事件处理程序：

     • keyup：当用户在 tbMessage 文本框中键入并在用户按“Enter”键调用 send 函数时触发。
     • click：当用户选择“发送”按钮并调用 send 函数时触发。

     HubConnectionBuilder 类创建新的生成器，用于配置服务器连接。 withUrl 函数配置中心 URL。

     SignalR 启用客户端和服务器之间的消息交换。 每个消息都有特定的名称。 例如，名为 messageReceived 的消息可以运行负责在消息区域显示新消息的逻辑。 可以通过 on 函数完成对特定消息的侦听。 可以侦听任意数量的消息名称。 还可以将参数传递到消息，例如所接收消息的作者姓名和内容。 客户端收到一条消息后，会创建一个新的 div 元素并在其 innerHTML 属性中显示作者姓名和消息内容。 它添加到显示消息的主要 div 元素。

     通过 WebSockets 连接发送消息需要调用 send 方法。 该方法的第一个参数是消息名称。 消息数据包含其他参数。 在此示例中，一条标识为 newMessage 的消息已发送到服务器。 该消息包含用户名和文本框中的用户输入。 如果发送成功，会清空文本框。

8. 在项目根目录运行以下命令：

   npm i @microsoft/signalr @types/node
   

   上述的代码会安装：

   • SignalR TypeScript 客户端，它允许客户端向服务器发送消息。
   • 用于 node.js 的 TypeScript 类型定义，支持 Node.js 类型的编译时检查。

测试应用程序

确认应用遵循以下步骤：

Visual Studio

1. 在 release 模式下运行 Webpack。 使用“包管理器控制台”窗口，在项目根目录中运行以下命令。

   npm run release
   

   此命令在运行应用时生成要提供的客户端资产。 资产位于 wwwroot 文件夹。

   Webpack 完成了以下任务：

   • 清除了 wwwroot 目录的内容。
   • 将 TypeScript 转换为 JavaScript，该过程称为“转译” 。
   • 破坏生成的 JavaScript 以降低文件大小，该过程称为“缩小” 。
   • 将已处理的 JavaScript、CSS 和 HTML 文件从 src 复制到 wwwroot 目录。
   • 将以下元素注入 wwwroot/index.html 文件：
     • 一个引用 wwwroot/main.<hash>.css 文件的 <link> 标记。 此标记紧挨着 </head> 结束标记之前。
     • 一个引用缩小后的 wwwroot/main.<hash>.js 文件的 <script> 标记。 此标记紧挨着 </title> 结束标记之后。

2. 选择“调试”>“开始执行(不调试)”，在不附加调试器的情况下在浏览器中启动应用 。 在 https://localhost:<port> 上提供 wwwroot/index.html 文件。

   如果存在编译错误，请尝试关闭并重新打开解决方案。

3. 打开另一个浏览器实例（任何浏览器），然后在地址栏中粘贴该 URL。

4. 选择一个浏览器，在“消息”文本框中键入任意内容，然后选择“发送”按钮。 两个页面上立即显示唯一的用户名和消息。

Visual Studio Code

1. 通过在项目根中执行以下命令以 release 模式运行 Webpack：

   npm run release
   

   此命令在运行应用时生成要提供的客户端资产。 资产位于 wwwroot 文件夹。

   Webpack 完成了以下任务：

   • 清除了 wwwroot 目录的内容。
   • 将 TypeScript 转换为 JavaScript，该过程称为“转译” 。
   • 破坏生成的 JavaScript 以降低文件大小，该过程称为“缩小” 。
   • 将已处理的 JavaScript、CSS 和 HTML 文件从 src 复制到 wwwroot 目录。
   • 将以下元素注入 wwwroot/index.html 文件：
     • 一个引用 wwwroot/main.<hash>.css 文件的 <link> 标记。 此标记紧挨着 </head> 结束标记之前。
     • 一个引用缩小后的 wwwroot/main.<hash>.js 文件的 <script> 标记。 此标记紧挨着 </title> 结束标记之后。

2. 通过在项目根中执行以下命令生成和运行应用：

   dotnet run
   

   Web 服务器启动应用并在 localhost 上提供。

3. 打开浏览器，转到 https://localhost:<port>。 提供 wwwroot/index.html 文件。 从地址栏复制 URL。

4. 打开另一个浏览器实例（任意浏览器）。 在地址栏中粘贴 URL。

5. 选择一个浏览器，在“消息”文本框中键入任意内容，然后选择“发送”按钮。 两个页面上立即显示唯一的用户名和消息。

后续步骤

• 强类型中心
• ASP.NET Core SignalR 中的身份验证和授权
• ASP.NET Core 的 SignalR 中的 MessagePack 中心协议

其他资源

• ASP.NET Core SignalR JavaScript 客户端
• 使用 ASP.NET Core 中的中心SignalR