Samouczek: rozpoczynanie pracy z platformą ASP.NET Core SignalR przy użyciu języka TypeScript i pakietu WebPack

Autor: Sébastien Sougnez

W tym samouczku pokazano używanie pakietu Webpack w aplikacji internetowej ASP.NET Core SignalR w celu tworzenia pakietu i kompilowania klienta napisanego w języku TypeScript. Pakiet Webpack umożliwia deweloperom łączenie i tworzenie zasobów po stronie klienta aplikacji internetowej.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

• Tworzenie aplikacji ASP.NET Core SignalR
• SignalR Konfigurowanie serwera
• Konfigurowanie potoku kompilacji przy użyciu pakietu WebPack
• SignalR Konfigurowanie klienta Języka TypeScript
• Włączanie komunikacji między klientem a serwerem

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Wymagania wstępne

• Node.js za pomocą narzędzia npm

Program Visual Studio

• Program Visual Studio 2022 z pakietem roboczym tworzenia aplikacji ASP.NET i aplikacji internetowych.

  

Visual Studio Code

• Visual Studio Code
• Język C# dla programu Visual Studio Code (najnowsza wersja)
• Zestaw SDK platformy .NET 8.0

W przypadku funkcji programistycznych platformy ASP.NET Core, takich jak tworzenie projektu, w instrukcjach programu Visual Studio Code wykorzystywany jest interfejs wiersza polecenia platformy .NET. Można postępować według tych instrukcji w systemach macOS, Linux lub Windows oraz w przypadku każdego edytora kodu. Jeśli korzystasz z programu innego niż Visual Studio Code, konieczne mogą być drobne zmiany.

Tworzenie aplikacji internetowej platformy ASP.NET Core

Program Visual Studio

Domyślnie program Visual Studio używa wersji narzędzia npm znalezionej w katalogu instalacyjnym. Aby skonfigurować program Visual Studio pod kątem wyszukiwania narzędzia npm w zmiennej środowiskowej PATH :

Uruchom program Visual Studio. W oknie startowym wybierz pozycję Kontynuuj bez kodu.

1. Przejdź do pozycji Narzędzia>Opcje>Projekty i rozwiązania>Web Package Management>Zewnętrzne narzędzia sieci Web.

2. $(PATH) Wybierz wpis z listy. Wybierz strzałkę w górę, aby przenieść wpis na drugą pozycję na liście, a następnie wybierz przycisk OK:

   .

Aby utworzyć nową aplikację internetową ASP.NET Core:

1. Użyj opcji menu Plik>nowy>projekt i wybierz szablon ASP.NET Core Empty. Wybierz Dalej.
2. Nadaj projektowi SignalRWebpacknazwę , a następnie wybierz pozycję Utwórz.
3. Z listy rozwijanej Framework wybierz pozycję .NET 8.0 (obsługa długoterminowa). Wybierz pozycję Utwórz.

Dodaj pakiet NuGet Microsoft.TypeScript.MSBuild do projektu:

1. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy węzeł projektu i wybierz polecenie Zarządzaj pakietami NuGet. Na karcie Przeglądaj wyszukajMicrosoft.TypeScript.MSBuild, a następnie wybierz pozycję Zainstaluj po prawej stronie, aby zainstalować pakiet.

Program Visual Studio dodaje pakiet NuGet w węźle Zależności w Eksplorator rozwiązań, włączając kompilację języka TypeScript w projekcie.

Visual Studio Code

Uruchom następujące polecenia w zintegrowanym terminalu:

dotnet new web -o SignalRWebpack
code -r SignalRWebpack

• Polecenie dotnet new tworzy pustą aplikację internetową ASP.NET Core w SignalRWebpack katalogu.
• Polecenie code otwiera SignalRWebpack katalog w bieżącym wystąpieniu programu Visual Studio Code.

Program Visual Studio Code może wyświetlić okno dialogowe z pytaniem: Czy ufasz autorom plików w tym folderze?

• Jeśli ufasz wszystkim plikom w folderze nadrzędnym, wybierz pozycję Ufaj autorom wszystkich plików w folderze nadrzędnym.
• Wybierz pozycję Tak. Ufam autorom , ponieważ folder projektu zawiera pliki wygenerowane przez platformę .NET.
• Gdy program Visual Studio Code zażąda dodania zasobów do kompilowania i debugowania projektu, wybierz pozycję Tak. Jeśli program Visual Studio Code nie oferuje dodawania zasobów kompilacji i debugowania, wybierz pozycję Wyświetl>paletę poleceń i wpisz ".NET" w polu wyszukiwania. Z listy poleceń wybierz .NET: Generate Assets for Build and Debug polecenie .

Program Visual Studio Code dodaje .vscode folder z wygenerowanymi launch.json plikami i tasks.json .

Uruchom następujące polecenie interfejsu wiersza polecenia platformy .NET w zintegrowanym terminalu:

dotnet add package Microsoft.TypeScript.MSBuild

Poprzednie polecenie dodaje pakiet Microsoft.TypeScript.MSBuild , włączając kompilację języka TypeScript w projekcie.

Konfigurowanie serwera

W tej sekcji skonfigurujesz aplikację internetową platformy ASP.NET Core do wysyłania i odbierania SignalR komunikatów.

1. W Program.cspliku wywołaj metodę AddSignalR:

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

2. Ponownie w pliku Program.cswywołaj metodę UseDefaultFiles i UseStaticFiles:

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

   Powyższy kod umożliwia serwerowi lokalizowanie i obsługę index.html pliku. Plik jest obsługiwany, czy użytkownik wprowadza pełny adres URL, czy główny adres URL aplikacji internetowej.

3. Utwórz nowy katalog o nazwie Hubs w katalogu głównym SignalRWebpack/projektu , dla SignalR klasy centrum.

4. Utwórz nowy plik z Hubs/ChatHub.csnastępującym kodem:

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

   Powyższy kod rozgłasza odebrane komunikaty do wszystkich połączonych użytkowników po odebraniu ich przez serwer. Nie trzeba mieć ogólnej on metody odbierania wszystkich komunikatów. Wystarczy metoda o nazwie o nazwie komunikatu.

   W tym przykładzie:

   • Klient TypeScript wysyła komunikat zidentyfikowany jako newMessage.
   • Metoda języka C# NewMessage oczekuje danych wysyłanych przez klienta.
   • Wywołanie jest wykonywane na SendAsync stronie Clients.All.
   • Odebrane komunikaty są wysyłane do wszystkich klientów połączonych z koncentratorem.

5. Dodaj następującą using instrukcję w górnej części, Program.cs aby rozwiązać ChatHub ten problem:

   using SignalRWebpack.Hubs;
   

6. W Program.cspliku zamapuj /hubChatHub trasę na koncentrator. Zastąp kod wyświetlany Hello World! następującym kodem:

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

Konfigurowanie klienta

W tej sekcji utworzysz projekt Node.js , aby przekonwertować język TypeScript na język JavaScript i powiązać zasoby po stronie klienta, w tym html i CSS, przy użyciu pakietu WebPack.

1. Uruchom następujące polecenie w katalogu głównym projektu, aby utworzyć package.json plik:

   npm init -y
   

2. Dodaj wyróżnioną właściwość do package.json pliku i zapisz zmiany w pliku:

   {
     "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 Ustawienie właściwości w celu true uniemożliwinia instalowania pakietów ostrzeżeń w następnym kroku.

3. Zainstaluj wymagane pakiety npm. Uruchom następujące polecenie z poziomu głównego projektu:

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

   Opcja -E wyłącza domyślne zachowanie narzędzia npm podczas pisania operatorów zakresu obsługi wersji semantycznych na package.json. Na przykład "webpack": "5.76.1" jest używany zamiast "webpack": "^5.76.1". Ta opcja uniemożliwia niezamierzone uaktualnienia do nowszych wersji pakietów.

   Aby uzyskać więcej informacji, zobacz dokumentację npm-install .

4. Zastąp scripts właściwość package.json pliku następującym kodem:

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

   Zdefiniowane są następujące skrypty:

   • build: łączy zasoby po stronie klienta w trybie programowania i obserwuje zmiany plików. Obserwator plików powoduje ponowne wygenerowanie pakietu za każdym razem, gdy zmienia się plik projektu. Opcja mode wyłącza optymalizacje produkcyjne, takie jak drżenie drzewa i minimalizowanie. używać build tylko w środowisku programistycznym.
   • release: łączy zasoby po stronie klienta w trybie produkcyjnym.
   • publish: uruchamia release skrypt, aby powiązać zasoby po stronie klienta w trybie produkcyjnym. Wywołuje polecenie publikowania interfejsu wiersza polecenia platformy .NET w celu opublikowania aplikacji.

5. Utwórz plik o nazwie webpack.config.js w katalogu głównym projektu z następującym kodem:

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

   Powyższy plik konfiguruje proces kompilacji pakietu WebPack:

   • Właściwość output zastępuje wartość domyślną .dist Pakiet jest zamiast tego emitowany w wwwroot katalogu.
   • Tablica resolve.extensions obejmuje .js importowanie SignalR kodu JavaScript klienta.

6. Utwórz nowy katalog o nazwie src w katalogu głównym SignalRWebpack/projektu , dla kodu klienta.

7. src Skopiuj katalog i jego zawartość z przykładowego projektu do katalogu głównego projektu. Katalog src zawiera następujące pliki:

   • index.html, który definiuje standardowy znacznik strony głównej:

     <!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, który udostępnia style CSS dla strony głównej:

     *,
     *::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, który konfiguruje kompilator TypeScript w celu utworzenia kodu JAVAScript zgodnego z językiem 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 = ""));
     }
     

     Powyższy kod pobiera odwołania do elementów DOM i dołącza dwa programy obsługi zdarzeń:

     • keyup: jest uruchamiany, gdy użytkownik wpisze w tbMessage polu tekstowym i wywołuje send funkcję, gdy użytkownik naciska klawisz Enter .
     • click: jest wyzwalany, gdy użytkownik wybierze przycisk Wyślij i wywoła send funkcję .

     Klasa HubConnectionBuilder tworzy nowego konstruktora do konfigurowania połączenia serwera. Funkcja withUrl konfiguruje adres URL centrum.

     SignalR umożliwia wymianę komunikatów między klientem a serwerem. Każda wiadomość ma określoną nazwę. Na przykład komunikaty o nazwie messageReceived mogą uruchamiać logikę odpowiedzialną za wyświetlanie nowego komunikatu w strefie komunikatów. Nasłuchiwanie określonego komunikatu on można wykonać za pośrednictwem funkcji . Można nasłuchiwać dowolnej liczby nazw wiadomości. Istnieje również możliwość przekazania parametrów do wiadomości, takich jak nazwa autora i zawartość odebranego komunikatu. Gdy klient otrzyma komunikat, zostanie utworzony nowy div element z nazwą autora i zawartością komunikatu w jego innerHTML atrybucie. Jest dodawany do głównego div elementu wyświetlającego komunikaty.

     Wysłanie komunikatu za pośrednictwem połączenia WebSockets wymaga wywołania send metody . Pierwszy parametr metody to nazwa komunikatu. Dane komunikatu zamieszkają inne parametry. W tym przykładzie komunikat zidentyfikowany jako newMessage jest wysyłany do serwera. Komunikat składa się z nazwy użytkownika i danych wejściowych użytkownika z pola tekstowego. Jeśli wysyłanie działa, wartość pola tekstowego zostanie wyczyszczone.

8. Uruchom następujące polecenie w katalogu głównym projektu:

   npm i @microsoft/signalr @types/node
   

   Poprzednie polecenie instaluje:

   • SignalR Klient TypeScript, który umożliwia klientowi wysyłanie komunikatów do serwera.
   • Definicje typów języka TypeScript dla Node.js, które umożliwiają sprawdzanie czasu kompilacji typów Node.js.

Testowanie aplikacji

Upewnij się, że aplikacja działa z następującymi krokami:

Program Visual Studio

1. Uruchom pakiet webpack w release trybie. Za pomocą okna konsoli Menedżer pakietów uruchom następujące polecenie w katalogu głównym projektu.

   npm run release
   

   To polecenie generuje zasoby po stronie klienta, które mają być obsługiwane podczas uruchamiania aplikacji. Zasoby są umieszczane w folderze wwwroot .

   Pakiet Webpack wykonał następujące zadania:

   • Przeczyścił zawartość wwwroot katalogu.
   • Przekonwertowano język TypeScript na język JavaScript w procesie znanym jako transpilacja.
   • Wygenerowany kod JavaScript został wygenerowany w celu zmniejszenia rozmiaru pliku w procesie znanym jako minification.
   • Skopiowano przetworzone pliki JavaScript, CSS i HTML z src katalogu wwwroot .
   • W pliku wstrzyknął następujące elementy wwwroot/index.html :
     • <link> Tag, odwołując wwwroot/main.<hash>.css się do pliku. Ten tag jest umieszczany bezpośrednio przed tagiem zamykającym </head> .
     • <script> Tag, odwołując się do pliku minyfikowanegowwwroot/main.<hash>.js. Ten tag jest umieszczany natychmiast po tagu zamykającym </title> .

2. Wybierz pozycję Debuguj>Rozpocznij bez debugowania, aby uruchomić aplikację w przeglądarce bez dołączania debugera. Plik wwwroot/index.html jest obsługiwany pod adresem https://localhost:<port>.

   Jeśli występują błędy kompilacji, spróbuj zamknąć i ponownie otworzyć rozwiązanie.

3. Otwórz inne wystąpienie przeglądarki (dowolną przeglądarkę) i wklej adres URL na pasku adresu.

4. Wybierz jedną z przeglądarek, wpisz coś w polu tekstowym Wiadomość , a następnie wybierz przycisk Wyślij . Unikatowa nazwa użytkownika i komunikat są wyświetlane na obu stronach natychmiast.

Visual Studio Code

1. Uruchom pakiet Webpack w release trybie, wykonując następujące polecenie w katalogu głównym projektu:

   npm run release
   

   To polecenie generuje zasoby po stronie klienta, które mają być obsługiwane podczas uruchamiania aplikacji. Zasoby są umieszczane w folderze wwwroot .

   Pakiet Webpack wykonał następujące zadania:

   • Przeczyścił zawartość wwwroot katalogu.
   • Przekonwertowano język TypeScript na język JavaScript w procesie znanym jako transpilacja.
   • Wygenerowany kod JavaScript został wygenerowany w celu zmniejszenia rozmiaru pliku w procesie znanym jako minification.
   • Skopiowano przetworzone pliki JavaScript, CSS i HTML z src katalogu wwwroot .
   • W pliku wstrzyknął następujące elementy wwwroot/index.html :
     • <link> Tag, odwołując wwwroot/main.<hash>.css się do pliku. Ten tag jest umieszczany bezpośrednio przed tagiem zamykającym </head> .
     • <script> Tag, odwołując się do pliku minyfikowanegowwwroot/main.<hash>.js. Ten tag jest umieszczany natychmiast po tagu zamykającym </title> .

2. Skompiluj i uruchom aplikację, wykonując następujące polecenie w katalogu głównym projektu:

   dotnet run
   

   Serwer internetowy uruchamia aplikację i udostępnia ją na hoście lokalnym.

3. Otwórz przeglądarkę w witrynie https://localhost:<port>. Plik wwwroot/index.html jest obsługiwany. Skopiuj adres URL w pasku adresu.

4. Otwórz inne wystąpienie przeglądarki (dowolną przeglądarkę). Wklej adres URL na pasku adresu.

5. Wybierz jedną z przeglądarek, wpisz coś w polu tekstowym Wiadomość , a następnie wybierz przycisk Wyślij . Unikatowa nazwa użytkownika i komunikat są wyświetlane na obu stronach natychmiast.

Następne kroki

• Silnie typizowane koncentratory
• Uwierzytelnianie i autoryzacja w programie ASP.NET Core SignalR
• Protokół MessagePack Hub w systemie SignalR dla ASP.NET Core

Dodatkowe zasoby

• ASP.NET Core SignalR JavaScript client
• Używanie koncentratorów w technologii ASP.NET Core SignalR