Tutorial: Introdução ao ASP.NET Core SignalR usando TypeScript e Webpack

Por Sébastien Sougnez

Este tutorial demonstra como usar o Webpack em um aplicativo Web SignalR do ASP.NET Core para empacotar e compilar um cliente escrito em TypeScript. O Webpack habilita os desenvolvedores a agrupar e criar recursos de um aplicativo Web do lado do cliente.

Neste tutorial, você aprenderá a:

• Criar um aplicativo SignalR ASP.NET Core
• Configurar o servidor SignalR
• Configurar um pipeline de build usando o Webpack
• Configurar o cliente TypeScript do SignalR
• Habilitar a comunicação entre o cliente e o servidor

Exibir ou baixar código de exemplo (como baixar)

Pré-requisitos

• Node.js com npm

Visual Studio

• Visual Studio 2022 com a carga de trabalho de desenvolvimento Web e do ASP.NET.

  

Visual Studio Code

• Visual Studio Code
• C# para Visual Studio Code (versão mais recente)
• SDK DO .NET 8.0

As instruções do Visual Studio Code usam a CLI do .NET para funções de desenvolvimento do ASP.NET Core, como criação de projeto. Você pode seguir estas instruções no macOS, no Linux ou no Windows e com qualquer editor de código. Alterações secundárias poderão ser necessárias se você usar algo diferente do Visual Studio Code.

Criar o aplicativo Web do ASP.NET Core

Visual Studio

Por padrão, o Visual Studio usa a versão do npm encontrada no diretório de instalação. Para configurar o Visual Studio para pesquisar o npm na variável de ambiente PATH:

Inicie o Visual Studio. Na janela Iniciar, selecione Continuar sem código.

1. Navegue para Ferramentas>Opções>Projetos e Soluções>Gerenciamento de Pacotes da Web>Ferramentas da Web Externas.

2. Selecione a entrada $(PATH) na lista. Selecione aa seta para cima para mover a entrada para a segunda posição da lista e selecione OK:

   .

Para criar um aplicativo Web ASP.NET Core:

1. Use a opção do menu Arquivo>Novo>Projeto e escolha o modelo ASP.NET Core Vazio. Selecione Avançar.
2. Dê ao projeto o nome de SignalRWebpack e selecione Criar.
3. Selecione .NET 8.0 (suporte a longo prazo) na lista suspensa do Framework. Selecione Criar.

Adicione o pacote NuGet Microsoft.TypeScript.MSBuild ao projeto:

1. No Gerenciador de Soluções, clique com o botão direito do mouse no nó do projeto e selecione Gerenciar Pacotes NuGet. Na guia Procurar, pesquise Microsoft.TypeScript.MSBuild e selecione Instalar à direita para instalar o pacote.

O Visual Studio adiciona o pacote NuGet no nó Dependências no Gerenciador de Soluções, habilitando a compilação do TypeScript no projeto.

Visual Studio Code

Execute os comandos a seguir no Terminal Integrado:

dotnet new web -o SignalRWebpack
code -r SignalRWebpack

• O comando dotnet new cria um aplicativo Web ASP.NET Core vazio em um diretório SignalRWebpack.
• O comando code abre o diretório SignalRWebpack na instância atual do Visual Studio Code.

O Visual Studio Code pode exibir uma caixa de diálogo que pergunta: Você confia nos autores dos arquivos nessa pasta?

• Se você confiar em todos os arquivos da pasta principal, selecione Confiar nos autores de todos os arquivos na pasta principal.
• Selecione Sim, eu confio nos autores, já que a pasta do projeto tem arquivos gerados pelo .NET.
• Quando o Visual Studio Code solicitar que você adicione ativos para compilar e depurar o projeto, selecione Sim. Se o Visual Studio Code não se oferecer para adicionar ativos de build e depuração, selecione Exibir>Paleta de Comandos e digite ".NET" na caixa de pesquisa. Na lista de comandos, selecione o comando .NET: Generate Assets for Build and Debug.

O Visual Studio Code adiciona uma pasta .vscode com os arquivos launch.json e tasks.json gerados.

Execute o comando da CLI do .NET a seguir no Terminal Integrado:

dotnet add package Microsoft.TypeScript.MSBuild

O comando anterior adiciona o pacote Microsoft.TypeScript.MSBuild, habilitando a compilação do TypeScript no projeto.

Configurar o servidor

Nesta seção, você configurará o aplicativo Web ASP.NET Core para enviar e receber mensagens SignalR.

1. Em Program.cs, chame AddSignalR:

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

2. Novamente, em Program.cs, chame UseDefaultFiles e UseStaticFiles:

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

   O código anterior permite que o servidor localize e forneça o arquivo index.html. O arquivo é fornecido se o usuário insere sua URL completa ou a URL raiz do aplicativo Web.

3. Crie um novo diretório chamado de Hubs na raiz do projeto, SignalRWebpack/, para a classe de hub SignalR.

4. Crie um arquivo Hubs/ChatHub.cs com o código a seguir:

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

   O código precedente transmite as mensagens recebidas para todos os usuários conectados quando o servidor as recebe. Não é necessário ter um método genérico on para receber todas as mensagens. Um método nomeado com o nome da mensagem é suficiente.

   Neste exemplo:

   • O cliente TypeScript envia uma mensagem identificada como newMessage.
   • O método NewMessage de C# espera os dados enviados pelo cliente.
   • Uma chamada é feita para SendAsync em Clients.All.
   • As mensagens recebidas são enviadas a todos os clientes conectados ao hub.

5. Adicione a instrução using a seguir ao início do Program.cs para resolver a referência a ChatHub:

   using SignalRWebpack.Hubs;
   

6. No Program.cs, mapeie a rota /hub para o hub ChatHub. Substitua o código que exibe Hello World! pelo código a seguir:

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

Configurar o cliente

Nesta seção, você criará um projeto Node.js para converter o TypeScript em JavaScript e agrupar recursos do lado do cliente, incluindo HTML e CSS, usando o Webpack.

1. Execute o seguinte comando na raiz do projeto para criar um arquivo package.json:

   npm init -y
   

2. Adicione a propriedade realçada ao arquivo package.json e salve as alterações de arquivo:

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

   Definir a propriedade private como true evita avisos de instalação de pacote na próxima etapa.

3. Instalar os pacotes de npm exigidos. Execute o seguinte comando na raiz do projeto:

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

   A opção -E desabilita o comportamento padrão do npm de escrever os operadores de intervalo de versão semântica para package.json. Por exemplo, "webpack": "5.76.1" é usado em vez de "webpack": "^5.76.1". Essa opção evita atualizações não intencionais para versões de pacote mais recentes.

   Para obter mais informações, confira a documentação do npm-install.

4. Substitua a propriedade scripts do arquivo package.json pelo código a seguir:

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

   Os seguintes scripts são definidos:

   • build: agrupa os recursos do lado do cliente no modo de desenvolvimento e busca alterações no arquivo. O observador de arquivos faz com que o lote se regenere toda vez que um arquivo de projeto é alterado. A opção mode desabilita otimizações de produção, como tree shaking e minificação. use build somente no desenvolvimento.
   • release: agrupa recursos do lado do cliente no modo de produção.
   • publish: executa o script release para agrupar recursos do lado do cliente no modo de produção. Chama o comando publicar da CLI do .NET para publicar o aplicativo.

5. Crie um arquivo chamado webpack.config.js na raiz do projeto, com o seguinte código:

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

   O arquivo anterior configura o processo de compilação Webpack:

   • A propriedade output substitui o valor padrão do dist. Em vez disso, o lote é emitido no diretório wwwroot.
   • A matriz resolve.extensions inclui .js para importar o JavaScript do cliente SignalR.

6. Crie um novo diretório chamado de src na raiz do projeto, SignalRWebpack/, para a código do cliente.

7. Copie o diretório src e seu conteúdo do projeto de exemplo na raiz do projeto. O diretório src contém os seguintes arquivos:

   • index.html, que define a marcação de texto clichê da home page:

     <!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 fornece estilos CSS para a home page:

     *,
     *::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 o compilador TypeScript para produzir um JavaScript compatível com 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 = ""));
     }
     

     O código anterior recupera referências a elementos DOM e anexa dois manipuladores de eventos:

     • keyup: é acionado quando o usuário digita tbMessage na caixa de texto e chama a função send quando o usuário pressiona a tecla Enter.
     • click: é acionado quando o usuário seleciona o botão Enviar e a função de chamadas send é chamada.

     A classe HubConnectionBuilder cria um novo construtor para configurar a conexão do servidor. A função withUrl configura a URL do hub.

     O SignalR habilita a troca de mensagens entre um cliente e um servidor. Cada mensagem tem um nome específico. Por exemplo, mensagens com o nome messageReceived podem executar a lógica responsável por exibir a nova mensagem na zona de mensagens. É possível escutar uma mensagem específica por meio da função on. Qualquer número de nomes de mensagem pode ser ouvido. Também é possível passar parâmetros para a mensagem, como o nome do autor e o conteúdo da mensagem recebida. Quando o cliente recebe a mensagem, um novo elemento div é criado com o nome do autor e o conteúdo da mensagem em seu atributo innerHTML. Ele é adicionado ao elemento principal div que exibe as mensagens.

     Enviar uma mensagem por meio da conexão WebSockets exige uma chamada para o método send. O primeiro parâmetro do método é o nome da mensagem. Os dados da mensagem residem nos outros parâmetros. Neste exemplo, uma mensagem identificada como newMessage é enviada ao servidor. A mensagem é composta do nome de usuário e da entrada em uma caixa de texto. Se o envio for bem-sucedido, o valor da caixa de texto será limpo.

8. Execute o comando a seguir na raiz do projeto:

   npm i @microsoft/signalr @types/node
   

   O comando anterior instala:

   • O cliente TypeScript do SignalR, que permite ao cliente enviar mensagens para o servidor.
   • As definições de tipo TypeScript para Node.js, que permite a verificação em tempo de compilação de tipos de Node.js.

Testar o aplicativo

Confirme que o aplicativo funciona com as seguintes etapas:

Visual Studio

1. Execute o Webpack no modo release. Usando a janela Console do Gerenciador de Pacotes, execute o comando a seguir na raiz do projeto.

   npm run release
   

   Este comando gera o fornecimento dos ativos do lado do cliente ao executar o aplicativo. Os ativos são colocados na pasta wwwroot.

   O Webpack concluiu as seguintes tarefas:

   • Limpou o conteúdo do diretório wwwroot.
   • Converteu o TypeScript para JavaScript, um processo conhecido como transpilação.
   • Reduziu o tamanho do arquivo JavaScript gerado, um processo conhecido como minificação.
   • Copiou os arquivos JavaScript, CSS e HTML processados do src para o diretório wwwroot.
   • Injetou os seguintes elementos no arquivo wwwroot/index.html:
     • Uma marca <link>, fazendo referência ao arquivo wwwroot/main.<hash>.css. Essa marca é colocada imediatamente antes do fim da marca </head>.
     • Uma marca <script>, fazendo referência ao arquivo wwwroot/main.<hash>.js minimizado. Essa marca é colocada imediatamente após a marca </title> de fechamento.

2. Selecione Debug>Iniciar sem depuração para iniciar o aplicativo em um navegador sem anexar o depurador. O arquivo wwwroot/index.html é fornecido em https://localhost:<port>.

   Se houver erros de compilação, tente fechar e reabrir a solução.

3. Abra outra instância de navegador (qualquer navegador) e cole a URL na barra de endereços.

4. Escolha qualquer navegador, digite algo na caixa de texto Mensagem e selecione o botão Enviar. O nome de usuário exclusivo e a mensagem são exibidas em ambas as páginas instantaneamente.

Visual Studio Code

1. Execute o Webpack no modo de release executando o comando a seguir na raiz do projeto:

   npm run release
   

   Este comando gera o fornecimento dos ativos do lado do cliente ao executar o aplicativo. Os ativos são colocados na pasta wwwroot.

   O Webpack concluiu as seguintes tarefas:

   • Limpou o conteúdo do diretório wwwroot.
   • Converteu o TypeScript para JavaScript, um processo conhecido como transpilação.
   • Reduziu o tamanho do arquivo JavaScript gerado, um processo conhecido como minificação.
   • Copiou os arquivos JavaScript, CSS e HTML processados do src para o diretório wwwroot.
   • Injetou os seguintes elementos no arquivo wwwroot/index.html:
     • Uma marca <link>, fazendo referência ao arquivo wwwroot/main.<hash>.css. Essa marca é colocada imediatamente antes do fim da marca </head>.
     • Uma marca <script>, fazendo referência ao arquivo wwwroot/main.<hash>.js minimizado. Essa marca é colocada imediatamente após a marca </title> de fechamento.

2. Crie e execute o aplicativo executando o seguinte comando na raiz do projeto:

   dotnet run
   

   O servidor Web inicia o aplicativo e o disponibiliza no localhost.

3. Abra um navegador para https://localhost:<port>. O arquivo wwwroot/index.html é fornecido. Copie a URL da barra de endereços.

4. Abra outra instância do navegador (qualquer navegador). Cole a URL na barra de endereços.

5. Escolha qualquer navegador, digite algo na caixa de texto Mensagem e selecione o botão Enviar. O nome de usuário exclusivo e a mensagem são exibidas em ambas as páginas instantaneamente.

Próximas etapas

• Hubs fortemente tipados
• Autenticação e autorização no ASP.NET Core SignalR
• Protocolo do Hub MessagePack no SignalR para ASP.NET Core

Recursos adicionais

• Cliente ASP.NET Core JavaScriptSignalR
• Usar hubs no ASP.NET Core SignalR