Tutorial: Introducción a ASP.NET Core SignalR mediante TypeScript y Webpack

Por Sébastien Sougnez

En este tutorial se describe el uso de Webpack en una aplicación web ASP.NET Core SignalR para unir y crear un cliente escrito en TypeScript. Webpack permite a los desarrolladores agrupar y compilar los recursos del lado cliente de una aplicación web.

En este tutorial aprenderá a:

• Crear una aplicación SignalR de ASP.NET Core
• Configurar el servidor SignalR
• Configuración de una canalización de compilación mediante Webpack
• Configurar el cliente de TypeScript para SignalR
• Habilitar la comunicación entre el cliente y el servidor

Vea o descargue el código de ejemplo (cómo descargarlo)

Prerequisites

• Node.js con npm

Visual Studio

• Visual Studio 2022 con la carga de trabajo de ASP.NET y desarrollo web

  

Visual Studio Code

• Visual Studio Code
• C# para Visual Studio Code (versión más reciente)
• SDK de .NET 8

Las instrucciones de Visual Studio Code usan la CLI de .NET para las funciones de desarrollo de ASP.NET Core, como la creación de los proyectos. Puede seguir dichas instrucciones en macOS, Linux o Windows y con cualquier editor de código. Si usa otra herramienta que no sea Visual Studio Code, es posible que sea necesario realizar cambios menores.

Creación de la aplicación web ASP.NET Core

Visual Studio

De forma predeterminada, Visual Studio usa la versión de npm que se encuentra en su directorio de instalación. Para configurar Visual Studio a fin de buscar npm en la variable de entorno PATH:

Inicie Visual Studio. En la ventana de inicio, seleccione Continuar sin código.

1. Vaya a Herramientas>Opciones>Proyectos y soluciones>Administración de paquetes web>Herramientas web externas.

2. Seleccione la entrada $(PATH) en la lista. Seleccione la flecha arriba para mover la entrada a la segunda posición de la lista y seleccione Aceptar:

   .

Para crear una aplicación web de ASP.NET Core:

1. Use la opción de menú Archivo>Nuevo>Proyecto y seleccione la plantilla ASP.NET Core vacío. Seleccione Siguiente.
2. Asigne el nombre SignalRWebpack al proyecto y seleccione Crear.
3. Seleccione .NET 8.0 (Compatibilidad a largo plazo) en la lista desplegable Framework. Selecciona Crear.

Agregue el paquete NuGet Microsoft.TypeScript.MSBuild al proyecto:

1. En el Explorador de soluciones, haga clic con el botón derecho en el nodo del proyecto y seleccione Administrar paquetes NuGet. En la pestaña Examinar, busque Microsoft.TypeScript.MSBuild y, luego, seleccione Instalar a la derecha para instalar el paquete.

Visual Studio agrega el paquete NuGet en el nodo Dependencias del Explorador de soluciones, que habilita la compilación de TypeScript en el proyecto.

Visual Studio Code

Ejecute los comandos siguientes en el terminal integrado:

dotnet new web -o SignalRWebpack
code -r SignalRWebpack

• El comando dotnet new crea una aplicación web ASP.NET Core vacía en un directorio SignalRWebpack.
• El comando code abre el directorio SignalRWebpack en la instancia actual de Visual Studio Code.

Visual Studio Code puede mostrar un cuadro de diálogo en el que se le pregunta: ¿confía en los autores de los archivos de esta carpeta?

• Si confía en todos los archivos de la carpeta principal, seleccione Confiar en los autores de todos los archivos de la carpeta principal.
• Seleccione Sí, confío en los autores, ya que la carpeta del proyecto tiene archivos generados por .NET.
• Cuando Visual Studio Code le solicite que agregue recursos de compilación y depuración del proyecto, seleccione Sí. Si Visual Studio Code no ofrece agregar recursos de compilación y depuración, seleccione Ver>Paleta de comandos y escriba ".NET" en el cuadro de búsqueda. En la lista de comandos, seleccione el comando .NET: Generate Assets for Build and Debug.

Visual Studio Code agrega una carpeta .vscode con los archivos launch.json y tasks.json que se han generado.

Ejecute el comando siguiente de la CLI de .NET en el terminal integrado:

dotnet add package Microsoft.TypeScript.MSBuild

El comando anterior agrega el paquete Microsoft.TypeScript.MSBuild, que habilita la compilación de TypeScript en el proyecto.

Configuración del servidor

En esta sección, configurará la aplicación web ASP.NET Core para enviar y recibir mensajes SignalR.

1. En Program.cs, llame a AddSignalR:

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

2. De nuevo, en Program.cs, llame a UseDefaultFiles y UseStaticFiles:

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

   El código anterior permite que el servidor busque y entregue el archivo index.html. El archivo se entrega si el usuario escribe su dirección URL completa o la dirección URL raíz de la aplicación web.

3. Cree un directorio denominado Hubs en la raíz del proyecto, SignalRWebpack/, para la clase de centro SignalR.

4. Cree un archivo. Hubs/ChatHub.cs, con el código siguiente:

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

   El código anterior difunde los mensajes recibidos a todos los usuarios conectados, una vez que el servidor los recibe. No es necesario tener un método on genérico para recibir todos los mensajes. Basta con un método que tenga el nombre del mensaje.

   En este ejemplo:

   • El cliente de TypeScript envía un mensaje que se identifica como newMessage.
   • El método NewMessage de C# espera los datos enviados por el cliente.
   • Se realiza una llamada a SendAsync en Clients.All.
   • Los mensajes recibidos se envían a todos los clientes conectados al concentrador.

5. Agregue la instrucción using siguiente en la parte superior de Program.cs para resolver la referencia a ChatHub:

   using SignalRWebpack.Hubs;
   

6. En Program.cs, asigne la ruta /hub al centro ChatHub. Reemplace el código que muestra Hello World! por el siguiente:

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

Configurar el cliente

En esta sección, creará un proyecto de Node.js para convertir TypeScript en JavaScript y agrupar recursos del lado cliente, incluidos HTML y CSS, mediante Webpack.

1. Ejecute el comando siguiente en la raíz del proyecto para crear un archivo package.json:

   npm init -y
   

2. Agregue la propiedad resaltada al archivo package.json y guarde los cambios efectuados en el archivo:

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

   Si establece la propiedad private en true, evitará las advertencias de la instalación de paquetes en el paso siguiente.

3. Instale los paquetes npm necesarios. Ejecute el comando siguiente desde la raíz del proyecto:

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

   La opción -E deshabilita el comportamiento predeterminado de npm de escribir operadores de intervalo de control de versiones semántico en package.json. Por ejemplo, se usa "webpack": "5.76.1" en lugar de "webpack": "^5.76.1". Esta opción impide actualizaciones no deseadas a versiones más recientes del paquete.

   Para más información, vea la documentación de npm-install.

4. Reemplace la propiedad scripts del archivo package.json por el código siguiente:

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

   Se definen los siguientes scripts:

   • build: agrupa los recursos del lado cliente en modo de desarrollo y supervisa los cambios del archivo. El monitor de archivos hace que la agrupación se vuelva a generar cada vez que cambia un archivo del proyecto. La opción mode deshabilita las optimizaciones de producción, como la agitación del árbol y la minificación. Use build únicamente durante el desarrollo.
   • release: agrupa los recursos del lado cliente en modo de producción.
   • publish: ejecuta el script release para agrupar los recursos del lado cliente en modo de producción. Llama al comando publish de la CLI de .NET para publicar la aplicación.

5. Cree un archivo denominado webpack.config.js, en la raíz del proyecto, con el código siguiente:

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

   El archivo anterior configura el proceso de compilación de Webpack:

   • La propiedad output invalida el valor predeterminado de dist. En su lugar, la agrupación se genera en el directorio wwwroot.
   • La matriz resolve.extensions incluye .js para importar el código JavaScript del cliente de SignalR.

6. Cree un directorio denominado src en la raíz del proyecto, SignalRWebpack/, para el código de cliente.

7. Copie el directorio src y sus contenidos del proyecto de ejemplo en la raíz del proyecto. El directorio src contiene los siguientes archivos:

   • index.html, que define el marcado reutilizable de la página principal:

     <!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, que proporciona estilos CSS para la página principal:

     *,
     *::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, que configura el compilador de TypeScript para generar JavaScript compatible con 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");
     
       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 = ""));
     }
     

     En el código anterior se recuperan las referencias a elementos DOM y se adjuntan dos controladores de eventos:

     • keyup: se desencadena cuando el usuario escribe en el cuadro de texto tbMessage y llama a la función send cuando el usuario presiona la tecla Entrar.
     • click: se desencadena cuando el usuario selecciona el botón Enviar y se llama a la función send.

     La clase HubConnectionBuilder crea un generador para configurar la conexión al servidor. La función withUrl configura la dirección URL del concentrador.

     SignalR permite el intercambio de mensajes entre un cliente y un servidor. Cada mensaje tiene un nombre específico. Por ejemplo, puede haber mensajes con el nombre messageReceived que pueden ejecutar la lógica responsable de mostrar el nuevo mensaje en la zona de mensajes. La escucha a un mensaje concreto se puede realizar mediante la función on. Se puede escuchar cualquier número de nombres de mensaje. También se pueden pasar parámetros al mensaje, como el nombre del autor y el contenido del mensaje recibido. Una vez que el cliente recibe un mensaje, se crea un elemento div con el nombre del autor y el contenido del mensaje en su atributo innerHTML. Se agrega al elemento div principal que muestra los mensajes.

     El envío de mensajes a través de la conexión de WebSockets requiere llamar al método send. El primer parámetro del método es el nombre del mensaje. Los datos del mensaje se encuentran en los otros parámetros. En este ejemplo, se envía al servidor un mensaje identificado como newMessage. El mensaje está formado por el nombre de usuario y la entrada del usuario desde un cuadro de texto. Si el envío funciona, se borra el valor del cuadro de texto.

8. Ejecute el comando siguiente en la raíz del proyecto:

   npm i @microsoft/signalr @types/node
   

   El comando anterior instala lo siguiente:

   • El cliente TypeScript de SignalR, que permite al cliente enviar mensajes al servidor.
   • Las definiciones de tipo de TypeScript para Node.js, que habilita la comprobación en tiempo de compilación de los tipos de Node.js.

Pruebas de la aplicación

Confirme que la aplicación funciona con los pasos siguientes:

Visual Studio

1. Ejecute Webpack en modo release. Desde la ventana Consola del Administrador de paquetes, ejecute el comando siguiente en la raíz del proyecto.

   npm run release
   

   Este comando genera la entrega de los recursos del lado cliente al ejecutar la aplicación. Los recursos se colocan en la carpeta wwwroot.

   Webpack ha completado las tareas siguientes:

   • Purgar el contenido del directorio wwwroot.
   • Convertir el lenguaje TypeScript en JavaScript, proceso conocido como transpilación.
   • Alterar el código JavaScript generado para reducir el tamaño del archivo, proceso conocido como minificación.
   • Copiar los archivos JavaScript, CSS y HTML procesados desde src en el directorio wwwroot.
   • Se han insertado los elementos siguientes en el archivo wwwroot/index.html:
     • Una etiqueta <link>, que hace referencia al archivo wwwroot/main.<hash>.css. Esta etiqueta se coloca inmediatamente antes de la etiqueta </head> de cierre.
     • Una etiqueta <script>, que hace referencia al archivo wwwroot/main.<hash>.js minificado. Esta etiqueta se coloca inmediatamente después de la etiqueta </title> de cierre.

2. Seleccione Depurar>Iniciar sin depurar para iniciar la aplicación en un explorador sin adjuntar el depurador. El archivo wwwroot/index.html se entrega en https://localhost:<port>.

   Si hay errores de compilación, intente cerrar y volver a abrir la solución.

3. Abra otra instancia del explorador (cualquier explorador) y pegue la dirección URL en la barra de direcciones.

4. Elija un explorador, escriba algo en el cuadro de texto Mensaje y seleccione el botón Enviar. El nombre de usuario único y el mensaje se muestran en las dos páginas al instante.

Visual Studio Code

1. Ejecute Webpack en modo release mediante la ejecución del comando siguiente en la raíz del proyecto:

   npm run release
   

   Este comando genera la entrega de los recursos del lado cliente al ejecutar la aplicación. Los recursos se colocan en la carpeta wwwroot.

   Webpack ha completado las tareas siguientes:

   • Purgar el contenido del directorio wwwroot.
   • Convertir el lenguaje TypeScript en JavaScript, proceso conocido como transpilación.
   • Alterar el código JavaScript generado para reducir el tamaño del archivo, proceso conocido como minificación.
   • Copiar los archivos JavaScript, CSS y HTML procesados desde src en el directorio wwwroot.
   • Se han insertado los elementos siguientes en el archivo wwwroot/index.html:
     • Una etiqueta <link>, que hace referencia al archivo wwwroot/main.<hash>.css. Esta etiqueta se coloca inmediatamente antes de la etiqueta </head> de cierre.
     • Una etiqueta <script>, que hace referencia al archivo wwwroot/main.<hash>.js minificado. Esta etiqueta se coloca inmediatamente después de la etiqueta </title> de cierre.

2. Compile y ejecute la aplicación mediante la ejecución del comando siguiente en la raíz del proyecto:

   dotnet run
   

   El servidor web inicia la aplicación y hace que esté disponible en el host local.

3. Abra un explorador en https://localhost:<port>. Se entrega el archivo wwwroot/index.html. Copie la dirección URL de la barra de direcciones.

4. Abra otra instancia del explorador (sirve cualquiera). Pegue la dirección URL en la barra de direcciones.

5. Elija un explorador, escriba algo en el cuadro de texto Mensaje y seleccione el botón Enviar. El nombre de usuario único y el mensaje se muestran en las dos páginas al instante.

Pasos siguientes

• Concentradores fuertemente tipados
• Autenticación y autorización en ASP.NET Core SignalR
• Protocolo de concentrador MessagePack de SignalR para ASP.NET Core

Recursos adicionales

• Cliente de JavaScript en ASP.NET Core SignalR
• Uso de concentradores en para ASP.NET CoreSignalR