教學課程：使用 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

Visual Studio

• 最新版本的 Visual Studio 具備 ASP.NET 與網頁開發工作負載。

  

Visual Studio 程式碼

• Visual Studio 程式碼
• 適用於 Visual Studio Code 的 C# 開發套件
• .NET 10.0 SDK

您可以遵循 macOS、Linux 或 Windows 上的 Visual Studio Code 指示。 如果您使用 Visual Studio Code 以外的整合式開發環境 (IDE)，則可能需要進行變更。

建立 ASP.NET Core Web 應用程式

Visual Studio

根據預設，Visual Studio 會使用在其安裝目錄中找到的 npm 版本。 若要設定 Visual Studio 以在 PATH 環境變數中尋找 npm：

啟動最新版本的 Visual Studio。 在 [開始] 視窗中，選取 [不使用程式碼繼續]。

1. 巡覽至 [工具]>[選項]>[專案和方案]>[網頁套件管理]>[外部 Web 工具]。

2. 從清單中選取 $(PATH) 項目。 選取向上箭號，將此項目移至清單中的第二個位置，然後選取 [確定]：

   

若要建立新的 ASP.NET Core Web 應用程式：

1. 請使用 「檔案>新>專案/解決方案... 」選單選項。
2. 在 「建立新專案 」對話框中，選擇 ASP.NET Core Empty 範本。 然後選取下一步。
3. 在 [設定新專案] 對話方塊中，輸入 SignalRWebpack 作為 [專案名稱]。 選取 下一步。
4. 在「附加資訊」對話框中，從框架下拉選單選擇 .NET 10.0（長期支援）。 選取 ，創建。

將 Microsoft.TypeScript.MSBuild NuGet 套件新增至專案：

1. 在 解決方案總管中，右鍵點擊專案節點，選擇 管理 NuGet 套件...。
2. 在 [瀏覽] 索引標籤中搜尋 Microsoft.TypeScript.MSBuild，然後選取右側的 [安裝] 以安裝套件。
3. 在 預覽變更 對話框中，選擇 套用。
4. 在 [接受授權] 對話方塊中，選取 [我接受]。

Visual Studio 會在方案總管的 [相依性] 節點底下新增 NuGet 套件，而在專案中啟用 TypeScript 編譯。

Visual Studio 程式碼

在 終端機執行以下指令：

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. 在專案根目錄 Hubs 中，為 SignalRWebpack/ 中樞類別建立名為 SignalR 的新目錄。

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 上呼叫 。
   • 接收的訊息就會傳送到連線至中樞的所有用戶端。

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");
     
       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 文字方塊時引發，並且在使用者按 send 鍵時呼叫 函式。
     • click：在使用者選取 [傳送] 按鈕並呼叫 send 函式時引發。

     HubConnectionBuilder 類別會建立用於設定伺服器連線的新產生器。 withUrl 函式則會設定中樞 URL。

     SignalR 可讓用戶端與伺服器之間進行訊息交換。 每個訊息都有特定的名稱。 例如，名稱為 messageReceived 的訊息可以執行負責在訊息區域中顯示新訊息的邏輯。 接聽特定的訊息可透過 on 函式完成。 可以接聽任意數目的訊息名稱。 也可將參數傳遞給訊息，例如作者的名稱和已接收訊息的內容。 用戶端收到訊息之後，就會在其 div 屬性中使用作者的名稱和訊息內容建立新的 innerHTML 元素。 它會新增至顯示訊息的主要 div 元素。

     透過 Websocket 連線傳送訊息需要呼叫 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 檔案中：
     • 一個 <link> 標籤，參考 wwwroot/main.<hash>.css 檔案。 此標記緊接在結尾 </head> 標記之前。
     • 一個 <script> 標籤，參考已縮減的 wwwroot/main.<hash>.js 檔案。 此標籤緊接在 </title> 結尾標籤後面。

2. 選取 [偵錯]>[啟動但不偵錯]，啟動瀏覽器中的應用程式，但不附加偵錯工具。 wwwroot/index.html 檔案會提供於 https://localhost:<port>。

   如果發生編譯錯誤，請嘗試將解決方案關閉再重新開啟。

3. 開啟另一個瀏覽器執行個體 (任何瀏覽器)，並在網址列中貼上 URL。

4. 選擇其中一個瀏覽器，在 [訊息] 文字方塊中鍵入某些內容，然後選取 [傳送] 按鈕。 唯一使用者名稱和訊息會立即顯示在兩個頁面上。

Visual Studio 程式碼

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
• SignalR for ASP.NET Core 中的 MessagePack 中樞通訊協定

其他資源

• ASP.NET Core SignalR JavaScript 用戶端
• 在 ASP.NET Core SignalR 中使用中樞