Tutorial: Erste Schritte mit ASP.NET Core SignalR mit TypeScript und Webpack

Von Sébastien Sougnez

In diesem Tutorial wird veranschaulicht, wie Webpack in einer ASP.NET Core SignalR-Web-App verwendet wird, um einen in TypeScript geschriebenen Client zu bündeln und zu erstellen. Mit Webpack können Entwickler clientseitige Ressourcen einer Web-App bündeln und erstellen.

In diesem Tutorial lernen Sie Folgendes:

• Erstellen einer ASP.NET Core SignalR-App
• Konfigurieren des SignalR-Servers
• Konfigurieren einer Buildpipeline mithilfe von Webpack
• Konfigurieren des SignalR-TypeScript-Clients
• Herstellen der Kommunikation zwischen dem Client und dem Server

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Voraussetzungen

• Node.js mit NPM

Visual Studio

• Visual Studio 2022 mit der Workload ASP.NET und Webentwicklung

  

Visual Studio Code

• Visual Studio Code
• C# für Visual Studio Code (neueste Version)
• .NET 8.0 SDK

In den Visual Studio Code-Anweisungen wird die .NET CLI für ASP.NET Core-Entwicklungsfunktionen wie die Projekterstellung verwendet. Sie können diese Schritte unter macOS, Linux oder Windows sowie in jedem beliebigen Code-Editor ausführen. Kleinere Änderungen sind möglicherweise erforderlich, wenn Sie ein anderes Programm als Visual Studio Code verwenden.

Erstellen einer ASP.NET Core-Web-App

Visual Studio

Visual Studio verwendet standardmäßig die Version von NPM, die sich im Installationsverzeichnis befindet. So konfigurieren Sie Visual Studio, damit in der Umgebungsvariablen PATH nach npm gesucht wird:

Starten Sie Visual Studio. Wählen Sie im Startfenster die Option Ohne Code fortfahren aus.

1. Navigieren Sie zu Extras>Optionen>Projekte und Projektmappen>Webpaketverwaltung>Externe Webtools.

2. Wählen Sie in der Liste den Eintrag $(PATH) aus. Drücken Sie die NACH-OBEN-TASTE, um den Eintrag auf die zweite Position in der Liste zu verschieben, und wählen Sie OK aus:

   .

So erstellen Sie eine neue ASP.NET Core-Web-App:

1. Verwenden Sie die Menüoption Datei>Neu>Projekt, und wählen Sie die Vorlage ASP.NET Core (leer) aus. Wählen Sie Weiter aus.
2. Geben Sie dem Projekt den Namen SignalRWebpack, und wählen Sie Erstellen aus.
3. Wählen Sie .NET 8.0 (Langfristiger Support) aus der Dropdownliste Framework aus. Wählen Sie Erstellen aus.

Fügen Sie das NuGet-Paket Microsoft.TypeScript.MSBuild zum Projekt hinzu:

1. Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Projektknoten, und wählen Sie NuGet-Pakete verwalten aus. Suchen Sie auf der Registerkarte Durchsuchen nach Microsoft.TypeScript.MSBuild, und wählen Sie dann rechts Installieren aus, um das Paket zu installieren.

Visual Studio fügt das NuGet-Paket unter dem Knoten Abhängigkeiten im Projektmappen-Explorer hinzu, wodurch die TypeScript-Kompilierung im Projekt aktiviert wird.

Visual Studio Code

Führen Sie im integrierten Terminal die folgenden Befehle aus:

dotnet new web -o SignalRWebpack
code -r SignalRWebpack

• Durch den Befehl dotnet new wird eine leere ASP.NET Core-Web-App in einem SignalRWebpack-Verzeichnis erstellt.
• Der Befehl code öffnet das Verzeichnis SignalRWebpack in der aktuellen Instanz von Visual Studio Code.

In Visual Studio Code wird ggf. ein Dialogfeld mit der Frage Vertrauen Sie den Autoren der Dateien in diesem Ordner? angezeigt.

• Wenn Sie allen Dateien im übergeordneten Ordner vertrauen, wählen Sie Den Autoren aller Dateien im übergeordneten Ordner vertrauen aus.
• Wählen Sie Ja, ich vertraue den Autoren aus, da der Projektordner von .NET generierte Dateien enthält.
• Wenn Visual Studio Code Sie auffordert, Ressourcen zum Erstellen und Debuggen des Projekts hinzuzufügen, wählen Sie Ja aus. Wenn Visual Studio Code keine Build- und Debugressourcen hinzufügen kann, wählen Sie Ansicht>Befehlspalette aus, und geben Sie „.NET“ in das Suchfeld ein. Wählen Sie in der Liste der Befehle den Befehl .NET: Generate Assets for Build and Debug aus.

Visual Studio Code fügt einen .vscode-Ordner mit den generierten launch.json- und tasks.json-Dateien hinzu.

Führen Sie im integrierten Terminal den folgenden .NET-CLI-Befehl aus:

dotnet add package Microsoft.TypeScript.MSBuild

Über den vorherigen Befehl wird das Paket Microsoft.TypeScript.MSBuild hinzugefügt, wodurch die TypeScript-Kompilierung im Projekt aktiviert wird.

Konfigurieren des Servers

In diesem Abschnitt konfigurieren Sie die ASP.NET Core-Web-App zum Senden und Empfangen von SignalR-Nachrichten.

1. Rufen Sie AddSignalR in Program.cs auf:

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

2. Rufen Sie in Program.cs nun UseDefaultFiles und UseStaticFiles auf:

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

   Der vorherige Code ermöglicht dem Server, die index.html-Datei zu finden und bereitzustellen. Die Datei wird bereitgestellt, wenn der Benutzer die vollständige URL oder nur die Stamm-URL der Web-App eingibt.

3. Erstellen Sie im Projektstamm Hubs ein neues Verzeichnis namens SignalRWebpack/ für die SignalR-Hubklasse.

4. Erstellen Sie die neue Datei Hubs/ChatHub.cs mit dem folgenden Code:

   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);
   }
   

   Der vorangehende Code überträgt die empfangenen Nachrichten an alle verbundenen Benutzer, sobald der Server sie empfängt. Es ist nicht notwendig, eine generische on-Methode zum Empfangen aller Nachrichten zu verwenden. Eine Methode mit dem gleichen Namen wie die Nachricht genügt.

   In diesem Beispiel:

   • Der TypeScript-Client sendet eine Nachricht, die als newMessage erkannt wurde.
   • Die C#-Methode NewMessage erwartet die vom Client gesendeten Daten.
   • Es erfolgt ein Aufruf an SendAsync für Clients.All.
   • Die empfangenen Nachrichten werden an alle mit dem Hub verbundenen Clients gesendet.

5. Fügen Sie die folgende using-Anweisung am Anfang von Program.cs ein, um den ChatHub-Verweis aufzulösen:

   using SignalRWebpack.Hubs;
   

6. Ordnen Sie in Program.cs die Route /hub dem Hub ChatHub zu. Ersetzen Sie den Code für Hello World! durch den folgenden Code:

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

Konfigurieren des Clients

In diesem Abschnitt erstellen Sie ein Node.js-Projekt , um TypeScript in JavaScript zu konvertieren und clientseitige Ressourcen, einschließlich HTML und CSS, mithilfe von Webpack zu bündeln.

1. Führen Sie den folgenden Befehl im Projektstamm aus, um eine package.json-Datei zu erstellen:

   npm init -y
   

2. Fügen Sie der package.json-Datei die hervorgehobene Eigenschaft hinzu, und speichern Sie die Dateiänderungen:

   {
     "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"
   }
   

   Durch Festlegen der Eigenschaft private auf true werden Warnungen bei der Paketinstallation im nächsten Schritt verhindert.

3. Installieren Sie die erforderlichen NPM-Pakete. Führen Sie den folgenden Befehl über den Projektstamm aus:

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

   Die Option -E deaktiviert das Standardverhalten von npm, das Bereichsoperatoren für die semantische Versionsverwaltung in die Datei package.json schreibt. Beispielsweise wird "webpack": "5.76.1" anstelle von "webpack": "^5.76.1" verwendet. Diese Option verhindert unbeabsichtigte Upgrades auf neuere Paketversionen.

   Weitere Informationen finden Sie in der Dokumentation zu npm-install.

4. Ersetzen Sie die scripts-Eigenschaft der Datei package.json durch den folgenden Code:

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

   Die folgenden Skripts sind definiert:

   • build: Bündelt die clientseitigen Ressourcen im Entwicklungsmodus und prüft auf Änderungen an Dateien. Der Dateiwatcher generiert das Bündel jedes Mal neu, wenn eine Änderung an einer Projektdatei vorgenommen wird. Die Option mode deaktiviert Produktionsoptimierungsvorgänge wie das „Tree Shaking“ und die „Minimierung“. Verwenden Sie build nur bei der Entwicklung.
   • release: Bündelt clientseitige Ressourcen im Produktionsmodus
   • publish: Führt das release-Skript aus, um die clientseitigen Ressourcen im Produktionsmodus zu bündeln. Es ruft den publish-Befehl der .NET-CLI auf, um die App zu veröffentlichen.

5. Erstellen Sie eine Datei namens webpack.config.js im Projektstamm mit dem folgenden Code:

   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",
           }),
       ],
   };
   

   Die vorangehende Datei konfiguriert den Webpack-Kompilierungsvorgang:

   • Die Eigenschaft output überschreibt den Standardwert von dist. Das Bündel wird stattdessen an das Verzeichnis wwwroot ausgegeben.
   • Das resolve.extensions-Array schließt .js ein, um den JavaScript-Code des SignalR-Clients zu importieren.

6. Erstellen Sie ein neues Verzeichnis namens src im Projektstamm (SignalRWebpack/) für den Clientcode.

7. Kopieren Sie das Verzeichnis src und dessen Inhalt aus dem Beispielprojekt in den Projektstamm. Das Verzeichnis src enthält die folgenden Dateien:

   • index.html, die die Markup-Codebausteine für die Homepage definiert:

     <!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, die CSS-Stile für die Homepage bereitstellt:

     *,
     *::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, die den TypeScript-Compiler dafür konfiguriert, JavaScript-Code zu generieren, der mit ECMAScript 5 kompatibel ist:

     {
       "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 = ""));
     }
     

     Der vorangehende Code ruft Verweise auf DOM-Elemente ab und fügt zwei Ereignishandler an:

     • keyup: Wird ausgelöst, wenn der*die Benutzer*in eine Eingabe im Textfeld tbMessage macht. Die Funktion send wird aufgerufen, wenn der*die Benutzer*in die EINGABETASTE drückt.
     • click: Wird ausgelöst, wenn der*die Benutzer*in die Schaltfläche Senden auswählt und die Funktion send aufgerufen wird.

     Die Klasse HubConnectionBuilder erstellt einen neuen Generator für die Konfiguration der Serververbindung. Die Funktion withUrl konfiguriert die Hub-URL.

     Mit SignalR wird der Austausch von Nachrichten zwischen einem Client und einem Server ermöglicht. Jede Nachricht verfügt über einen spezifischen Namen. Beispielsweise können Nachrichten mit dem Namen messageReceived die Logik zum Anzeigen neuer Nachrichten im Nachrichtenbereich ausführen. Mit der on-Funktion kann eine spezifische Nachricht belauscht werden. Sie können auf eine beliebige Anzahl von Nachrichtennamen lauschen. Außerdem können Parameter an die Nachricht übergeben werden, z.B. der Name des Autors und der Inhalt der empfangenen Nachricht. Sobald der Client eine Nachricht empfängt, wird ein neues div-Element mit dem Namen des Autors und dem Inhalt der Nachricht im innerHTML-Attribut erstellt. Es wird dem Hauptelement div hinzugefügt, das die Nachrichten anzeigt.

     Für das Senden einer Nachricht über die WebSockets-Verbindung ist das Aufrufen der Methode send erforderlich. Der erste Parameter der Methode ist der Name der Nachricht. Die Nachrichtendaten befinden sich in den anderen Parametern. In diesem Beispiel wird eine Nachricht, die als newMessage erkannt wird, an den Server gesendet. Die Nachricht besteht aus dem Benutzernamen und der Benutzereingabe eines Textfelds. Wenn das Senden funktioniert hat, wird der Textfeldwert gelöscht.

8. Führen Sie den folgenden Befehl auf der Ebene des Projektstamms aus:

   npm i @microsoft/signalr @types/node
   

   Mit dem vorangestellten Komma wird Folgendes installiert:

   • Der SignalR-TypeScript-Client, mit dem der Client Nachrichten an den Server senden kann.
   • Die TypeScript-Typdefinitionen für Node.js, die die Überprüfung zur Kompilierzeit von Node.js-Typen ermöglichen

Testen der App

Mit den folgenden Schritten können Sie überprüfen, ob die App funktioniert:

Visual Studio

1. Führen Sie Webpack im release aus. Führen Sie im Fenster Paket-Manager-Konsole den folgenden Befehl im Projektstammverzeichnis aus.

   npm run release
   

   Dieser Befehl generiert die clientseitigen Objekte an, die bereitgestellt werden, wenn die App ausgeführt wird. Die Objekte werden im Ordner wwwroot gespeichert.

   Webpack hat die folgenden Aufgaben durchgeführt:

   • Die Inhalte des Verzeichnis wwwroot wurden bereinigt.
   • TypeScript wurde in JavaScript konvertiert. Dieser Prozess ist als Transpilierung bekannt.
   • Der generierte JavaScript-Code wurde gekürzt, um die Dateigröße zu reduzieren. Dieser Prozess ist als Minimierung bekannt.
   • Die verarbeiteten JavaScript-, CSS- und HTML-Dateien wurden aus src in das Verzeichnis wwwroot kopiert.
   • Die folgenden Elemente wurden in die Datei wwwroot/index.html eingefügt:
     • Ein <link>-Tag, das auf die wwwroot/main.<hash>.css-Datei verweist Dieses Tag wird unmittelbar vor dem schließenden Tag </head> platziert.
     • Ein <script>-Tag, das auf die verkleinerte wwwroot/main.<hash>.js-Datei verweist Dieses Tag wird unmittelbar nach dem schließenden </title>-Tag eingefügt.

2. Klicken Sie auf Debuggen>Starten ohne Debugging, um die App in einem Browser zu starten, ohne den Debugger anzufügen. Die Datei wwwroot/index.html wird unter https://localhost:<port> bereitgestellt.

   Wenn Kompilierungsfehler auftreten, versuchen Sie, die Projektmappe zu schließen und erneut zu öffnen.

3. Öffnen Sie eine andere Instanz eines beliebigen Browsers, und fügen Sie die URL in die Adressleiste ein.

4. Wählen Sie einen beliebigen Browser aus, geben Sie etwas im Textfeld Nachricht ein, und wählen Sie Senden aus. Der eindeutige Benutzername und die Nachricht werden sofort auf beiden Seiten angezeigt.

Visual Studio Code

1. Führen Sie Webpack im release aus, indem Sie den folgenden Befehl im Projektstamm ausführen:

   npm run release
   

   Dieser Befehl generiert die clientseitigen Objekte an, die bereitgestellt werden, wenn die App ausgeführt wird. Die Objekte werden im Ordner wwwroot gespeichert.

   Webpack hat die folgenden Aufgaben durchgeführt:

   • Die Inhalte des Verzeichnis wwwroot wurden bereinigt.
   • TypeScript wurde in JavaScript konvertiert. Dieser Prozess ist als Transpilierung bekannt.
   • Der generierte JavaScript-Code wurde gekürzt, um die Dateigröße zu reduzieren. Dieser Prozess ist als Minimierung bekannt.
   • Die verarbeiteten JavaScript-, CSS- und HTML-Dateien wurden aus src in das Verzeichnis wwwroot kopiert.
   • Die folgenden Elemente wurden in die Datei wwwroot/index.html eingefügt:
     • Ein <link>-Tag, das auf die wwwroot/main.<hash>.css-Datei verweist Dieses Tag wird unmittelbar vor dem schließenden Tag </head> platziert.
     • Ein <script>-Tag, das auf die verkleinerte wwwroot/main.<hash>.js-Datei verweist Dieses Tag wird unmittelbar nach dem schließenden </title>-Tag eingefügt.

2. Erstellen Sie die App, und führen Sie sie aus, indem Sie den folgenden Befehl im Projektstamm ausführen:

   dotnet run
   

   Der Webserver beginnt mit der App und stellt sie auf „localhost“ zur Verfügung.

3. Öffnen Sie https://localhost:<port> im Browser. Die Datei wwwroot/index.html wird bereitgestellt. Kopieren Sie die URL aus der Adressleiste.

4. Öffnen Sie eine weitere Browserinstanz (beliebiger Browser). Fügen Sie die URL in die Adressleiste ein.

5. Wählen Sie einen beliebigen Browser aus, geben Sie etwas im Textfeld Nachricht ein, und wählen Sie Senden aus. Der eindeutige Benutzername und die Nachricht werden sofort auf beiden Seiten angezeigt.

Nächste Schritte

• Stark typisierte Hubs
• Authentifizierung und Autorisierung in ASP.NET CoreSignalR
• MessagePack Hub Protocol in SignalR für ASP.NET Core

Zusätzliche Ressourcen

• SignalR-JavaScript-Client in ASP.NET Core
• Verwenden von Hubs in in ASP.NET CoreSignalR