Tutoriel : Bien démarrer avec ASP.NET Core SignalR à l’aide de TypeScript et Webpack

Ce tutoriel montre comment utiliser Webpack dans une application web ASP.NET Core SignalR pour regrouper et générer un client écrit en TypeScript. Webpack permet aux développeurs de regrouper et générer les ressources côté client d’une application web.

Dans ce tutoriel, vous allez apprendre à :

• Créer une application ASP.NET Core SignalR
• Configurer le serveur SignalR
• Configurer un pipeline de build à l’aide de Webpack
• Configurer le client TypeScript SignalR
• Activer la communication entre le client et le serveur

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Prerequisites

• Node.js avec npm

Visual Studio

• La dernière version de Visual Studio avec la charge de travail de développement ASP.NET et web .

  

Visual Studio Code

• Visual Studio Code
• Kit de développement C# pour Visual Studio Code
• SDK .NET 10.0

Vous pouvez suivre les instructions de Visual Studio Code sur macOS, Linux ou Windows. Des modifications peuvent être nécessaires si vous utilisez un environnement de développement intégré (IDE) autre que Visual Studio Code.

Créer l’application web ASP.NET Core

Visual Studio

Par défaut, Visual Studio utilise la version de npm qu’il trouve dans son répertoire d’installation. Pour configurer Visual Studio pour rechercher npm dans la variable d’environnement PATH :

Lancez la dernière version de Visual Studio. Dans la fenêtre de démarrage, sélectionnez Continuer sans code.

1. Accédez à Outils>Options>Projets et solutions>Gestion des packages web>Outils web externes.

2. Sélectionnez l’entrée $(PATH) dans la liste. Sélectionnez la flèche vers le haut pour déplacer l’entrée à la deuxième position de la liste, puis sélectionnez OK :

   

Pour créer une application web ASP.NET Core :

1. Utilisez l’option de menu Fichier>Nouveau>Projet/Solution....
2. Dans la boîte de dialogue Créer un nouveau projet, sélectionnez le modèle ASP.NET Core Empty. Ensuite, sélectionnez Suivant.
3. Dans la boîte de dialogue Configurer votre nouveau projet, entrez SignalRWebpack pour nom du projet. Cliquez sur Suivant.
4. Dans la boîte de dialogue Informations supplémentaires , sélectionnez .NET 10.0 (Support à long terme) dans la liste déroulante Framework . Cliquez sur Créer.

Ajoutez le package NuGet Microsoft.TypeScript.MSBuild au projet :

1. Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet, puis sélectionnez Gérer les packages NuGet....
2. Sous l’onglet Parcourir, recherchez Microsoft.TypeScript.MSBuild, puis cliquez sur Installer à droite pour installer le package.
3. Dans la boîte de dialogue Aperçu des modifications , sélectionnez Appliquer.
4. Dans la boîte de dialogue Acceptation de la licence, sélectionnez J’accepte.

Visual Studio ajoute le package NuGet sous le nœud Dépendances dans Explorateur de solutions, ce qui permet la compilation TypeScript dans le projet.

Visual Studio Code

Exécutez les commandes suivantes dans le terminal :

dotnet new web -o SignalRWebpack
code -r SignalRWebpack

• La commande dotnet new crée une application web ASP.NET Core vide dans un répertoire SignalRWebpack.
• La commande code ouvre le répertoire SignalRWebpack dans l’instance actuelle de Visual Studio Code.

Visual Studio Code peut afficher une boîte de dialogue demandant : Faites-vous confiance aux auteurs des fichiers de ce dossier ?

• Si vous faites confiance à tous les fichiers du dossier parent, sélectionnez Faire confiance aux auteurs de tous les fichiers du dossier parent.
• Sélectionnez Oui, je fais confiance aux auteurs puisque le dossier du projet contient des fichiers générés par .NET.
• Lorsque Visual Studio Code vous demande d’ajouter des ressources pour générer et déboguer le projet, sélectionnez Oui. Si Visual Studio Code ne propose pas d’ajouter des ressources de construction et de débogage, sélectionnez Afficher>Palette de commandes et tapez « .NET » dans la zone de recherche. Dans la liste des commandes, sélectionnez la commande .NET: Generate Assets for Build and Debug.

Visual Studio Code ajoute un dossier .vscode avec les fichiers générés launch.json et tasks.json.

Exécutez la commande CLI .NET suivante dans le terminal :

dotnet add package Microsoft.TypeScript.MSBuild

La commande précédente ajoute le package Microsoft.TypeScript.MSBuild, ce qui active la compilation TypeScript dans le projet.

Configurer le serveur

Dans cette section, vous allez configurer l’application web ASP.NET Core pour envoyer et recevoir des messages SignalR.

1. Dans Program.cs, appelez AddSignalR :

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

2. Là encore, dans Program.cs, appelez UseDefaultFiles et UseStaticFiles :

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

   Le code précédent permet au serveur de localiser et de servir le fichier index.html. Le fichier est servi si l’utilisateur entre son URL complète ou l’URL racine de l’application web.

3. Créez un répertoire nommé Hubs dans la racine du projet, SignalRWebpack/, pour la classe hub SignalR.

4. Créez un fichier, Hubs/ChatHub.cs, avec le code suivant :

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

   Le code précédent diffuse les messages reçus à tous les utilisateurs connectés, une fois que le serveur les reçoit. Vous n’avez pas besoin d’avoir recours à une méthode générique on pour recevoir tous les messages. Une méthode nommée après le nom du message est suffisante.

   Dans cet exemple :

   • Le client TypeScript envoie un message identifié comme newMessage.
   • La méthode C# NewMessage attend les données envoyées par le client.
   • Un appel est effectué pour SendAsync sur Clients.All.
   • Les messages reçus sont envoyés à tous les clients connectés au hub.

5. Ajoutez l’instruction using suivante en haut de Program.cs pour résoudre la référence ChatHub :

   using SignalRWebpack.Hubs;
   

6. Dans Program.cs, mappez l’itinéraire /hub au hub ChatHub. Remplacez le code qui affiche Hello World! par le code suivant :

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

Configurer le client

Dans cette section, vous allez créer un projet Node.js pour convertir TypeScript en ressources JavaScript et regrouper des ressources côté client, notamment HTML et CSS, à l’aide de Webpack.

1. Exécutez la commande suivante dans la racine du projet pour créer un fichier package.json :

   npm init -y
   

2. Ajoutez la propriété mise en surbrillance au fichier package.json et enregistrez les modifications apportées au fichier :

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

   La définition de la propriété private sur true empêche les avertissements d’installation de package à l’étape suivante.

3. Installez les packages npm nécessaires. À partir de la racine du projet, exécutez la commande suivante :

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

   L’option -E désactive le comportement par défaut de npm qui consiste à écrire des opérateurs de plage de versionnage sémantique dans package.json. Par exemple, "webpack": "5.76.1" peut être utilisé à la place de "webpack": "^5.76.1". Cette option empêche les mises à niveau involontaires vers des versions de package plus récentes.

   Pour plus d’informations, consultez la documentation npm-install.

4. Remplacez la propriété scripts du fichier package.json par le code suivant :

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

   Les scripts suivants sont définis :

   • build : Regroupe les ressources côté client en mode de développement et surveille les changements de fichier. L’observateur de fichiers entraîne la régénération du paquet chaque fois qu’un fichier de projet change. L'option mode désactive les optimisations de production, telles que le tree shaking et la minification. utilisez build uniquement dans le développement.
   • release : Regroupe les ressources côté client en mode de production.
   • publish : Exécute le script release pour regrouper les ressources côté client en mode de production. La commande appelle la commande publish de CLI .NET pour publier l’application.

5. Créez un fichier nommé webpack.config.js à la racine du projet avec le code suivant :

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

   Le fichier précédent configure le processus de compilation Webpack :

   • La propriété output remplace la valeur par défaut de dist. Le paquet est plutôt émis dans le répertoire wwwroot.
   • Le tableau resolve.extensions inclut .js pour importer le code JavaScript du client SignalR.

6. Créez un nouveau répertoire nommé src à la racine du projet, SignalRWebpack/, pour le code client.

7. Copiez le répertoire src et son contenu de l'exemple de projet vers la racine du projet. Le répertoire src contient les fichiers suivants :

   • index.html, qui définit le balisage réutilisable de la page d’accueil :

     <!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, qui fournit des styles CSS pour la page d’accueil :

     *,
     *::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, qui configure le compilateur TypeScript pour produire du JavaScript compatible ECMAScript 5 :

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

     Le code précédent récupère les références aux éléments DOM et attache deux gestionnaires d’événements :

     • keyup : se déclenche lorsque l’utilisateur tape dans la zone de texte tbMessage et appelle la fonction send lorsque l’utilisateur appuie sur la touche Entrée.
     • click : se déclenche lorsque l’utilisateur sélectionne le bouton Envoyer et la fonction send est appelée.

     La classe HubConnectionBuilder crée un générateur pour configurer la connexion de serveur. La fonction withUrl configure l’URL du hub.

     SignalR permet l’échange de messages entre un client et un serveur. Chaque message a un nom spécifique. Par exemple, les messages portant le nom messageReceived peuvent exécuter la logique responsable de l’affichage du nouveau message dans la zone de messages. L’écoute d’un message spécifique peut être effectuée au moyen de la fonction on. N’importe quel nombre de noms de messages peuvent être écoutés. Vous pouvez aussi passer des paramètres au message, comme le nom de l’auteur et le contenu du message reçu. Une fois que le client reçoit un message, un nouvel élément div est créé avec le nom de l'auteur et le contenu du message ajoutés en tant qu'éléments enfants à l'aide de textContent. Il est ajouté à l’élément div principal qui affiche les messages.

     L’envoi d’un message au moyen de la connexion WebSocket nécessite l’appel de la méthode send. Le premier paramètre de la méthode est le nom du message. Les données du message se trouvent dans les autres paramètres. Dans cet exemple, un message identifié comme newMessage est envoyé au serveur. Le message se compose du nom d’utilisateur et de l’entrée de l’utilisateur dans une zone de texte. Si l’envoi réussit, la valeur de la zone de texte est effacée.

8. Exécutez la commande suivante à la racine du projet :

   npm i @microsoft/signalr @types/node
   

   La commande précédente active :

   • Le SignalRclient TypeScript, ce qui permet au client d’envoyer des messages au serveur.
   • Les définitions de types TypeScript pour Node.js, qui permettent la vérification au moment de la compilation des types Node.js.

Tester l'application

Vérifiez que l’application fonctionne avec les étapes suivantes :

Visual Studio

1. Exécutez Webpack en mode release. Dans la fenêtre Console du Gestionnaire de package, exécutez la commande suivante à la racine du projet.

   npm run release
   

   Cette commande génère les ressources côté client à délivrer pendant l’exécution de l’application. Les ressources sont placées dans le dossier wwwroot.

   Webpack a effectué les tâches suivantes :

   • Vide le contenu du répertoire wwwroot.
   • Converti le TypeScript en JavaScript dans un processus appelé transpilation.
   • Modifié le code JavaScript généré pour réduire la taille du fichier dans un processus appelé minification.
   • Copie des fichiers JavaScript, CSS et HTML traités à partir de src dans le répertoire wwwroot.
   • Injection des éléments suivants dans le fichier wwwroot/index.html :
     • Balise <link>, référençant le fichier wwwroot/main.<hash>.css. Cette balise est placée immédiatement avant la balise </head> de fermeture.
     • Balise <script>, référençant le fichier wwwroot/main.<hash>.js minifié. Cette balise est placée immédiatement après la balise de fermeture </title>.

2. Sélectionnez Déboguer>Démarrer sans débogage pour lancer l’application dans un navigateur sans attacher le débogueur. Le fichier wwwroot/index.html est disponible à https://localhost:<port>.

   En cas d’erreurs de compilation, essayez de fermer et de rouvrir la solution.

3. Ouvrez une autre instance du navigateur (n’importe quel navigateur) et collez l’URL dans la barre d’adresse.

4. Choisissez un navigateur, tapez quelque chose dans la zone de texte Message, puis cliquez sur le bouton Envoyer. Le nom unique de l’utilisateur et le message sont affichés instantanément dans les deux pages.

Visual Studio Code

1. Exécutez Webpack en mode de release en exécutant la commande suivante à la racine du projet :

   npm run release
   

   Cette commande génère les ressources côté client à délivrer pendant l’exécution de l’application. Les ressources sont placées dans le dossier wwwroot.

   Webpack a effectué les tâches suivantes :

   • Vide le contenu du répertoire wwwroot.
   • Converti le TypeScript en JavaScript dans un processus appelé transpilation.
   • Modifié le code JavaScript généré pour réduire la taille du fichier dans un processus appelé minification.
   • Copie des fichiers JavaScript, CSS et HTML traités à partir de src dans le répertoire wwwroot.
   • Injection des éléments suivants dans le fichier wwwroot/index.html :
     • Balise <link>, référençant le fichier wwwroot/main.<hash>.css. Cette balise est placée immédiatement avant la balise </head> de fermeture.
     • Balise <script>, référençant le fichier wwwroot/main.<hash>.js minifié. Cette balise est placée immédiatement après la balise de fermeture </title>.

2. Générez et exécutez l’application en exécutant la commande suivante à la racine du projet :

   dotnet run
   

   Le serveur web démarre l’application et la rend disponible sur localhost.

3. Ouvrez un navigateur et accédez à https://localhost:<port>. Le fichier wwwroot/index.html est servi. Copiez l’URL de la barre d’adresse.

4. Ouvrez une autre instance de navigateur (n’importe quel navigateur). Copiez l’URL de la barre d’adresse.

5. Choisissez un navigateur, tapez quelque chose dans la zone de texte Message, puis cliquez sur le bouton Envoyer. Le nom unique de l’utilisateur et le message sont affichés instantanément dans les deux pages.

Étapes suivantes

• Hubs fortement typés
• Authentification et autorisation dans ASP.NET Core SignalR
• Protocole Hub MessagePack dans SignalR pour ASP.NET Core

Ressources supplémentaires

• Client JavaScript SignalR ASP.NET Core
• Utiliser des hubs dans ASP.NET Core SignalR