Учебник. Начало работы с ASP.NET Core SignalR с использованием TypeScript и Webpack.

Себастиен Сугнес

В этом учебнике демонстрируется использование средства Webpack для создания пакета и сборки веб-приложения ASP.NET Core SignalR, а также объединения и создания клиента, который написан на языке TypeScript. С помощью средства Webpack разработчики могут создавать пакеты и выполнять сборку ресурсов на стороне клиента для веб-приложения.

В этом руководстве описано следующее:

• Создание приложения ASP.NET Core SignalR
• настроить сервер SignalR.
• Настроить конвейер сборки с использованием Webpack
• настроить клиент TypeScript SignalR;
• Включение обмена данными между клиентом и сервером.

Просмотреть или скачать образец кода (описание загрузки)

Необходимые компоненты

• Node.js с npm

Visual Studio

• Visual Studio 2022 с рабочей нагрузкой ASP.NET и веб-разработка.

  

Visual Studio Code

• Visual Studio Code
• C# для Visual Studio Code (последняя версия)
• Пакет SDK для .NET 8.0

Для функций разработки ASP.NET Core, таких как создание проекта, в инструкциях Visual Studio Code используется .NET CLI. Эти инструкции можно выполнять на macOS, Linux или Windows и в любом редакторе кода. При использовании редактора, отличного от Visual Studio Code, может потребоваться внести незначительные изменения.

Создание веб-приложения ASP.NET Core

Visual Studio

По умолчанию Visual Studio использует версию npm, которая находится в его каталоге установки. Настройка Visual Studio на поиск npm в переменной среды PATH:

Запустите Visual Studio. В начальном окне выберите Продолжить без кода.

1. Выберите Сервис>Параметры>Проекты и решения>Управление веб-пакетами>Внешние веб-инструменты.

2. $(PATH) Выберите запись из списка. Щелкните стрелку вверх, чтобы переместить этот элемент на вторую позицию в списке, и нажмите OK.

   .

Создание веб-приложения ASP.NET Core:

1. Перейдите в меню Файл>Создать>Проект и выберите шаблон Пустой шаблон ASP.NET Core. Выберите Далее.
2. Задайте для проекта имя SignalRWebpack и нажмите кнопку Создать.
3. Выберите .NET 8.0 (долгосрочная поддержка) в раскрывающемся списке Платформы . Нажмите кнопку создания.

Добавьте в проект пакет NuGet Microsoft.TypeScript.MSBuild.

1. В обозревателе решений щелкните правой кнопкой мыши узел проекта и выберите Управление пакетами NuGet. На вкладке Обзор найдите Microsoft.TypeScript.MSBuild, а затем нажмите кнопку Установить справа, чтобы установить пакет.

Visual Studio добавляет пакет NuGet в узел Зависимости в обозревателе решений, разрешая компиляцию TypeScript в проекте.

Visual Studio Code

Во встроенном терминале выполните следующую команду:

dotnet new web -o SignalRWebpack
code -r SignalRWebpack

• Команда dotnet new создает пустое веб-приложение ASP.NET Core в каталоге SignalRWebpack.
• Команда code открывает каталог SignalRWebpack в текущем экземпляре Visual Studio Code.

Visual Studio Code может отобразить диалоговое окно с запросом: доверяете авторам файлов в этой папке?

• Если вы доверяете всем файлам в родительской папке, выберите "Доверять авторам всех файлов" в родительской папке.
• Выберите "Да", я доверяю авторам , так как папка проекта содержит файлы, созданные .NET.
• Когда Visual Studio Code запрашивает добавление ресурсов для сборки и отладки проекта, нажмите кнопку "Да". Если Visual Studio Code не предлагает добавлять ресурсы сборки и отладки, выберите представление>палитры команд и введите ".NET" в поле поиска. В списке команд выберите .NET: Generate Assets for Build and Debug команду.

Visual Studio Code добавляет папку .vscode с созданными и tasks.json файламиlaunch.json.

Во встроенном терминале выполните следующую команду .NET CLI:

dotnet add package Microsoft.TypeScript.MSBuild

Предыдущая команда добавляет пакет Microsoft.TypeScript.MSBuild, разрешая компиляцию TypeScript в проекте.

настроить сервер .

В этом разделе вы настроите веб-приложение ASP.NET Core для отправки и получения сообщений SignalR.

1. В Program.cs вызовите AddSignalR.

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

2. В Program.cs снова вызовите UseDefaultFiles и UseStaticFiles:

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

   Приведенный выше код позволяет серверу находить и обслуживать index.html файл. Файл обрабатывается независимо от того, вводит ли пользователь полный или корневой URL-адрес веб-приложения.

3. Создайте новый каталог с именем Hubs в корневом каталоге проекта SignalRWebpack/ для хранения класса концентратора SignalR.

4. Создайте файл Hubs/ChatHub.cs со следующим кодом:

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

   Приведенный выше код осуществляет широковещательную рассылку полученных сервером сообщений всем подключенным пользователям. Универсальный метод on для получения всех сообщений не требуется. Имя метода указывается после суффиксов имени сообщения.

   В этом примере:

   • Клиент TypeScript отправляет сообщение, определенное как newMessage.
   • Метод C# NewMessage ожидает данные, отправленные клиентом.
   • Выполняется вызов метода SendAsync для Clients.All.
   • Полученные сообщения отправляются всем клиентам, подключенным к концентратору.

5. Добавьте следующий оператор using в самое начало Program.cs, чтобы разрешить ссылку ChatHub:

   using SignalRWebpack.Hubs;
   

6. В Program.cs сопоставьте маршрут /hub с концентратором ChatHub. Замените код, отображающий сообщение Hello World!, следующим кодом:

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

Настройка клиента

В этом разделе вы создадите проект Node.js для преобразования TypeScript в JavaScript и объединения ресурсов на стороне клиента, включая HTML и CSS, с помощью Webpack.

1. Выполните следующую команду в корневом package.json каталоге проекта, чтобы создать файл:

   npm init -y
   

2. Добавьте выделенное свойство в package.json файл и сохраните изменения файла:

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

   Если свойству private присвоено значение true, на следующем шаге не будут отображаться предупреждения об установке пакета.

3. Установите необходимые пакеты npm. Выполните следующую команду из корневого каталога проекта:

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

   Использование параметра -E позволяет отключить установленное по умолчанию поведение npm, предусматривающее запись операторов диапазона семантического управления версиями в файл package.json. Например, "webpack": "5.76.1" используется вместо "webpack": "^5.76.1". Этот параметр позволяет исключить непреднамеренное обновление до более новых версий пакета.

   Дополнительные сведения см. в npm-install.

4. Замените свойство scripts в файле package.json следующим кодом:

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

   Определены следующие скрипты:

   • build: объединяет клиентские ресурсы в режиме разработки и проверяет изменения файлов. Наблюдатель за файлами выполняет повторное создание пакета при каждом изменении файла проекта. Параметр mode позволяет отключить оптимизации в рабочей среде, такие как встряхивание дерева и минификация. build используется только в среде разработки.
   • release: объединяет клиентские ресурсы в рабочем режиме.
   • publish. Запускает скрипт release для создания пакета ресурсов на стороне клиента в рабочем режиме. Этот скрипт вызывает команду publish интерфейса командной строки .NET для публикации приложения.

5. Создайте файл с именем webpack.config.js в корневом каталоге проекта с помощью следующего кода:

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

   Приведенный выше файл определяет конфигурацию процесса компиляции Webpack.

   • Свойство output переопределяет значение distпо умолчанию. Пакет вместо этого создается в каталоге wwwroot .
   • Массив resolve.extensions включает в себя .js импорт клиентского SignalR JavaScript.

6. Создайте каталог с именем src в корневом каталоге SignalRWebpack/проекта для клиентского кода.

7. src Скопируйте каталог и его содержимое из примера проекта в корневой каталог проекта. Каталог src содержит следующие файлы:

   • index.html, который определяет стереотипную разметку главной страницы.

     <!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, который предоставляет стили CSS для главной страницы:

     *,
     *::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, который определяет конфигурацию компилятора TypeScript для получения совместимого с ECMAScript 5 кода JavaScript.

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

     Приведенный выше код извлекает ссылки на элементы модели DOM и присоединяет два обработчика событий:

     • keyup: срабатывает, когда пользователь вводит данные в текстовое поле tbMessage, и вызывает функцию send при нажатии пользователем клавиши Enter.
     • click: срабатывает, когда пользователь нажимает кнопку Отправить и вызывается функцию send.

     Класс HubConnectionBuilder создает новый построитель для настройки подключения к серверу. Функция withUrl настраивает URL-адрес концентратора.

     SignalR обеспечивает обмен сообщениями между клиентом и сервером. Каждому сообщению присваивается определенное имя. Например, сообщения с именем messageReceived могут выполнять логику отображения новых сообщений в соответствующей зоне. Прослушивание определенных сообщений реализуется с помощью функции on. Возможно прослушивание любого числа имен сообщений. Кроме того, можно передавать параметры сообщения, например имя его автора или содержимое полученного сообщения. После того как клиент получает сообщение, создается новый элемент div, в атрибуте innerHTML которого содержатся имя автора и содержимое сообщения. Этот элемент добавляется в основной элемент div, который используется для отображения сообщений.

     Для отправки сообщения через соединение WebSockets необходимо вызвать метод send. Первый параметр этого метода содержит имя сообщения. Другие параметры заполняются данными сообщения. В этом примере на сервер отправляется сообщение, идентифицированное как newMessage. Это сообщение содержит имя пользователя, а также данные, введенные этим пользователем в текстовое поле. Если отправка выполняется успешно, значение текстового поля очищается.

8. Выполните следующую команду в корневом элементе проекта:

   npm i @microsoft/signalr @types/node
   

   Предыдущая команда устанавливает:

   • Клиент TypeScript SignalR, который позволяет клиенту отправлять сообщения на сервер.
   • Определения типа TypeScript для Node.js, обеспечивающие проверку типов Node.js во время компиляции.

Тестирование приложения

Чтобы проверить работоспособность приложения, выполните следующие шаги.

Visual Studio

1. Запустите Webpack в release режиме. Выполните следующие команды в окне Консоль диспетчера пакетов в корневом элементе проекта.

   npm run release
   

   Эта команда создает ресурсы на стороне клиента, которые будут обслуживаться при выполнении приложения. Ресурсы помещаются в папку wwwroot .

   Веб-пакет выполнил следующие задачи:

   • Очистка содержимого wwwroot каталога.
   • Преобразование TypeScript в JavaScript (этот процесс называется транспилированием).
   • Корректировка созданного кода JavaScript в целях уменьшения размера файла (этот процесс называется минификацией).
   • Скопированы обработанные файлы JavaScript, CSS и HTML из srcwwwroot каталога.
   • В файл ввели следующие элементы wwwroot/index.html :
     • Тег <link>, ссылающийся на файл wwwroot/main.<hash>.css. Этот тег размещается непосредственно после закрывающего тега </head>.
     • Тег <script>, ссылающийся на минифицированный файл wwwroot/main.<hash>.js. Этот тег помещается сразу после закрывающего </title> тега.

2. Выберите Отладка>Запуск без отладки, чтобы запустить приложение в браузере, не присоединяя отладчик. Файл wwwroot/index.html обрабатывается по адресу https://localhost:<port>.

   Если возникают ошибки компиляции, попробуйте закрыть и повторно открыть решение.

3. Откройте другой экземпляр браузера (любого) и вставьте URL-адрес в адресную строку.

4. Выберите любой браузер, введите произвольный текст в поле Сообщение и нажмите кнопку Отправить. На обеих страницах мгновенно отображаются имя пользователя и сообщение.

Visual Studio Code

1. Запустите Webpack в release режиме, выполнив следующую команду в корневом каталоге проекта:

   npm run release
   

   Эта команда создает ресурсы на стороне клиента, которые будут обслуживаться при выполнении приложения. Ресурсы помещаются в папку wwwroot .

   Веб-пакет выполнил следующие задачи:

   • Очистка содержимого wwwroot каталога.
   • Преобразование TypeScript в JavaScript (этот процесс называется транспилированием).
   • Корректировка созданного кода JavaScript в целях уменьшения размера файла (этот процесс называется минификацией).
   • Скопированы обработанные файлы JavaScript, CSS и HTML из srcwwwroot каталога.
   • В файл ввели следующие элементы wwwroot/index.html :
     • Тег <link>, ссылающийся на файл wwwroot/main.<hash>.css. Этот тег размещается непосредственно после закрывающего тега </head>.
     • Тег <script>, ссылающийся на минифицированный файл wwwroot/main.<hash>.js. Этот тег помещается сразу после закрывающего </title> тега.

2. Выполните построение и запустите приложение, выполнив следующую команду в корневом элементе проекта:

   dotnet run
   

   Веб-сервер запускает приложение и делает его доступным на узле localhost.

3. Откройте в браузере страницу https://localhost:<port>. Файл wwwroot/index.html будет обработан. Скопируйте URL-адрес из адресной строки.

4. Откройте другой экземпляр любого браузера. Вставьте URL-адрес в адресную строку.

5. Выберите любой браузер, введите произвольный текст в поле Сообщение и нажмите кнопку Отправить. На обеих страницах мгновенно отображаются имя пользователя и сообщение.

Следующие шаги

• Строго типизированные центры
• Проверка подлинности и авторизация в ASP.NET Core SignalR
• Протокол MessagePack Hub для SignalR ASP.NET Core

Дополнительные ресурсы

• Клиент JavaScript SignalR ASP.NET Core
• Использование концентраторов в ASP.NET Core SignalR