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

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

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

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

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

Prerequisites

• Node.js 使用 npm

Visualstudio

• 最新版本的 Visual Studio 具有 ASP.NET 和 Web 开发 工作负载。

  

Visual Studio Code

• Visual Studio Code
• 适用于 Visual Studio Code 的 C# 开发工具包
• .NET 10.0 SDK

可以按照 macOS、Linux 或 Windows 上的 Visual Studio Code 指南进行操作。 如果使用 Visual Studio Code 以外的集成开发环境 (IDE)，可能需要更改。

创建 ASP.NET Core Web 应用

Visualstudio

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

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

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

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

   

新建 ASP.NET Core Web 应用：

1. 使用 “文件>新建>项目/解决方案...” 菜单选项。
2. 在“ 创建新项目 ”对话框中，选择 ASP.NET 核心空 模板。 然后选择下一步。
3. 在“配置新项目”对话框中，为“项目名称”SignalRWebpack输入 。 选择“下一步”。
4. 在“其他信息”对话框中，从框架下拉列表中选择 .NET 10.0（长期支持）。 选择 创建。

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

1. 在 解决方案资源管理器中，右键单击项目节点并选择“ 管理 NuGet 包...”。
2. 在“浏览”选项卡中，搜索 ，然后选择右侧的“安装”来安装包。
3. 在 “预览更改 ”对话框中，选择“ 应用”。
4. 在“许可接受”对话框中，选择“我接受”。

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 添加一个包含生成的 .vscode 和 launch.json 文件的 tasks.json 文件夹。

在 终端中运行以下 .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 方法需要客户端发送的数据。
   • 在 SendAsync 上发起对 Clients.All 的调用。
   • 接收的消息会发送到所有连接到中心的客户端。

5. 在 using 顶部添加以下 Program.cs 语句来解析 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": {
       "build": "webpack --mode=development --watch",
       "release": "webpack --mode=production",
       "publish": "npm run release && dotnet publish -c Release"
     },
     "keywords": [],
     "author": "",
     "license": "ISC",
     "type": "commonjs",
     "devDependencies": {
       "clean-webpack-plugin": "4.0.0",
       "css-loader": "7.1.3",
       "html-webpack-plugin": "5.6.6",
       "mini-css-extract-plugin": "2.10.0",
       "ts-loader": "9.5.4",
       "typescript": "5.9.3",
       "webpack": "5.104.1",
       "webpack-cli": "6.0.1"
     },
     "dependencies": {
       "@microsoft/signalr": "^10.0.0",
       "@types/node": "^25.0.10"
     }
   }
   

   将 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. 将 scripts 文件的 package.json 属性替换为以下代码：

   "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. 在项目根目录 src 中，为客户端代码创建名为 SignalRWebpack/ 的新目录。

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");
     
       const author = document.createElement("div");
       author.className = "message-author";
       author.textContent = username;
     
       const content = document.createElement("div");
       content.textContent = message;
     
       m.append(author, content);
     
       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：当用户选择“发送”按钮并调用 函数时触发。

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

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

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

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

   npm i @microsoft/signalr @types/node
   

   前面的命令会安装：

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

测试应用

确认应用遵循以下步骤：

Visualstudio

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

   npm run release
   

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

   Webpack 完成了以下任务：

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

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

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

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 文件：
     • 一个 <link> 标记，引用 wwwroot/main.<hash>.css 文件。 此标记放置在紧靠</head>结束标记之前。
     • 一个 <script> 标记，用于引用缩小后的 wwwroot/main.<hash>.js 文件。 此标记紧接在 </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