aspnetcore/tutorials/signalr.md
:::moniker range=">= aspnetcore-10.0"
This tutorial teaches the basics of building a real-time app using SignalR. You learn how to:
[!div class="checklist"]
- Create a web project.
- Add the SignalR client library.
- Create a SignalR hub.
- Configure the project to use SignalR.
- Add code that sends messages from any client to all connected clients.
At the end, you'll have a working chat app:
:::image type="content" source="~/tutorials/signalr/media/signalr-chat-app.png" alt-text="SignalR sample app.":::
Start the latest version of Visual Studio and select Create a new project.
:::image type="content" source="~/tutorials/signalr/media/start-window-create-new-project.png" alt-text="Create a new project from the start window.":::
In the Create a new project dialog, select ASP.NET Core Web App (Razor Pages), and then select Next.
:::image type="content" source="~/tutorials/signalr/media/new-aspnet-core-web-app.png" alt-text="Create an ASP.NET Core Web App.":::
In the Configure your new project dialog, enter SignalRChat for Project name. It's important to name the project SignalRChat, including matching the capitalization, so the namespaces match the code in the tutorial.
Select Next.
In the Additional information dialog, select .NET 10.0 (Long Term Support) and then select Create.
:::image type="content" source="~/tutorials/signalr/media/additional-information.png" alt-text="Additional information.":::
The tutorial assumes familiarity with VS Code. For more information, see Getting started with VS Code
cd) that will contain the project.dotnet new webapp -o SignalRChat
code -r SignalRChat
The dotnet new command creates a new Razor Pages project in the SignalRChat folder.
The code command opens the SignalRChat folder in the current instance of Visual Studio Code.
The SignalR server library is included in the ASP.NET Core shared framework. The JavaScript client library isn't automatically included in the project. For this tutorial, use Library Manager (LibMan) to get the client library from unpkg. unpkgis a fast, global content delivery network for everything on npm.
In Solution Explorer, right-click the project, and select Add > Client-Side Library.
In the Add Client-Side Library dialog:
@microsoft/signalr@latest for Library.signalr.js and signalr.min.js.wwwroot/js/signalr/.:::image type="content" source="~/tutorials/signalr/media/add-client-side-library.png" alt-text="Add Client-Side Library dialog - select library.":::
LibMan creates a wwwroot/js/signalr folder and copies the selected files to it. A libman.json file is created with the following code:
[!code-jsonChatHub]
In the integrated terminal, run the following commands to install LibMan after uninstalling any previous version, if one exists.
dotnet tool uninstall -g Microsoft.Web.LibraryManager.Cli
dotnet tool install -g Microsoft.Web.LibraryManager.Cli
Navigate to the project folder, which contains the SignalRChat.csproj file.
Run the following command to get the SignalR client library by using LibMan. It may take a few seconds before displaying output.
libman install @microsoft/signalr@latest -p unpkg -d wwwroot/js/signalr --files dist/browser/signalr.js
The parameters specify the following options:
wwwroot/js/signalr destination.The output looks similar to the following:
Downloading file https://unpkg.com/@microsoft/signalr@latest/dist/browser/signalr.js...
wwwroot/js/signalr/dist/browser/signalr.js written to disk
Installed library "@microsoft/signalr@latest" to "wwwroot/js/signalr"
A hub is a class that serves as a high-level pipeline that handles client-server communication.
In the SignalRChat project folder, create a Hubs folder.
In the Hubs folder, create the ChatHub class with the following code:
[!code-csharpChatHub]
The ChatHub class inherits from the SignalR xref:Microsoft.AspNetCore.SignalR.Hub class. The Hub class manages connections, groups, and messaging.
The SendMessage method can be called by a connected client to send a message to all clients. JavaScript client code that calls the method is shown later in the tutorial. SignalR code is asynchronous to provide maximum scalability.
The SignalR server must be configured to pass SignalR requests to SignalR. Add the following highlighted code to the Program.cs file.
[!code-csharpStartup]
The preceding highlighted code adds SignalR to the ASP.NET Core dependency injection and routing systems.
Replace the content in Pages/Index.cshtml with the following code:
[!code-cshtmlIndex]
The preceding markup:
id="messagesList" for displaying messages that are received from the SignalR hub.chat.js app code is created in the next step.In the wwwroot/js folder, create a chat.js file with the following code:
[!code-javascriptchat]
The preceding JavaScript:
Select <kbd>Ctrl</kbd>+<kbd>F5</kbd> to run the app without debugging.
Select <kbd>Ctrl</kbd>+<kbd>F5</kbd> to run the app without debugging.
Copy the URL from the address bar, open another browser instance or tab, and paste the URL in the address bar.
Choose either browser, enter a name and message, and select the Send Message button.
The name and message are displayed on both pages instantly.
:::image type="content" source="~/tutorials/signalr/media/signalr-chat-app.png" alt-text="Completed SignalR sample app.":::
[!TIP] If the app doesn't work, open the browser developer tools (F12) and go to the console. Look for possible errors related to HTML and JavaScript code. For example, if
signalr.jswas put in a different folder than directed, the reference to that file won't work resulting in a 404 error in the console. :::image type="content" source="~/tutorials/signalr/_static/7.x/f12-console.png" alt-text="signalr.js not found error."::: If anERR_SPDY_INADEQUATE_TRANSPORT_SECURITYerror has occurred in Chrome, run the following commands to update the development certificate:dotnetclidotnet dev-certs https --clean dotnet dev-certs https --trust
For information on deploying to Azure, see Quickstart: Deploy an ASP.NET web app. For more information on Azure SignalR Service, see What is Azure SignalR Service?.
:::moniker-end