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

By Sébastien Sougnez

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)

Prérequis

• Node.js avec npm

Visual Studio

• Visual Studio 2022 avec la charge de travail Développement web et ASP.NET.

  

Visual Studio Code

• Visual Studio Code
• C# pour Visual Studio Code (dernière version)
• SDK .NET 8.0

Les instructions Visual Studio Code utilisent les fonctions de développement de .NET CLI pour ASP.NET Core, comme la création de projet. Vous pouvez suivre ces instructions sur macOS, Linux ou Windows, et avec n’importe quel éditeur de code. Des modifications mineures peuvent être nécessaires si vous utilisez autre chose 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 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 et choisissez le modèle ASP.NET Core Vide. Cliquez sur Suivant.
2. Nommez le projet SignalRWebpack, puis sélectionnez Créer.
3. Sélectionnez .NET 8.0 (prise en charge à long terme) dans la liste déroulante Framework. Sélectionnez Créer.

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

1. Dans Explorateur de solutions, cliquez avec le bouton droit sur le nœud du projet, puis sélectionnez Gérer les packages NuGet. Sous l’onglet Parcourir, recherchez Microsoft.TypeScript.MSBuild, puis cliquez sur Installer à droite pour installer le package.

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 intégré :

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 intégré :

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’appeler 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 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": {
       "test": "echo \"Error: no test specified\" && exit 1"
     },
     "keywords": [],
     "author": "",
     "license": "ISC"
   }
   

   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 pour écrire contrôle de version sémantique opérateurs de plage pour 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 force la regénération du regroupement chaque fois qu’un fichier projet change. L’option mode désactive les optimisations de production, comme la minimisation de l’arborescence (tree shaking). 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 regroupement est émis dans le répertoire wwwroot à la place.
   • 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 javaScript compatible 5 ECMAScript :

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

     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 appelle send la fonction.

     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. Dès que le client reçoit un message, un élément div est créé avec le nom de l’auteur et le contenu du message dans son attribut innerHTML. 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 fonctionne, 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.
   • Définitions de type TypeScript pour Node.js, qui permet la vérification au moment de la compilation des types Node.js.

Test de 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.
   • Troncation du code JavaScript généré pour réduire la taille de fichier dans un processus appelé minimisation.
   • 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 servi à 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.
   • Troncation du code JavaScript généré pour réduire la taille de fichier dans un processus appelé minimisation.
   • 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 SignalRASP.NET Core
• Utiliser des hubs dans ASP.NET Core SignalR