SignalR Integration in ASP.NET Core: Building a Real-Time WebSocket Chat Application

Date- May 17,2026 78

signalr aspnetcore

Overview

SignalR is a library for ASP.NET that simplifies the process of adding real-time web functionality to applications. It allows server-side code to push content to connected clients instantly, providing an efficient solution for scenarios requiring live updates. The primary problem SignalR addresses is the challenge of maintaining a persistent connection with clients to facilitate the real-time exchange of information without the need for constant polling, which can be inefficient and resource-intensive.

Real-world use cases for SignalR include chat applications, live notifications, real-time dashboards, collaborative editing tools, and gaming applications. By leveraging WebSockets and other transport protocols, SignalR ensures that data can be transmitted efficiently between the server and the client, thus enhancing user experience and engagement.

Prerequisites

ASP.NET Core SDK: Ensure you have the latest version installed to work with SignalR.
Basic C# Knowledge: Understanding C# syntax and programming fundamentals is essential.
Familiarity with WebSockets: Knowing how WebSockets function can help you grasp SignalR's capabilities better.
Visual Studio or VS Code: A suitable IDE for developing your ASP.NET Core applications.

Setting Up SignalR in ASP.NET Core

The first step in integrating SignalR into your ASP.NET Core application is setting up the necessary packages. SignalR is included as a NuGet package, which you can easily install using the .NET CLI or through Visual Studio's NuGet Package Manager.

dotnet add package Microsoft.AspNetCore.SignalR

This command adds the SignalR library to your project, allowing you to use its features in your application. Once installed, you can configure SignalR in the Startup.cs file of your ASP.NET Core project.

public class Startup
{
  public void ConfigureServices(IServiceCollection services)
  {
      services.AddSignalR();
  }

  public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  {
      if (env.IsDevelopment())
      {
          app.UseDeveloperExceptionPage();
      }
      app.UseRouting();

      app.UseEndpoints(endpoints =>
      {
          endpoints.MapHub<ChatHub>("/chat");
      });
  }
}

In this code, we define a ChatHub class that will manage the connections and messaging between clients. The ConfigureServices method adds the SignalR services to the dependency injection container, while the Configure method sets up the routing to the SignalR hub.

Creating the ChatHub Class

A hub is a class that serves as a central point for communication between clients and the server. Here’s how you can create a basic ChatHub class:

using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;

public class ChatHub : Hub
{
  public async Task SendMessage(string user, string message)
  {
      await Clients.All.SendAsync("ReceiveMessage", user, message);
  }
}

In this ChatHub class, we define a method SendMessage that takes a username and a message as parameters. It uses the Clients.All.SendAsync method to broadcast the message to all connected clients. The ReceiveMessage method will need to be implemented on the client side to handle the incoming messages.

Building the Client-Side Application

In order to send and receive messages using SignalR, we need to implement the client-side code. This can be done using JavaScript. First, we need to include the SignalR JavaScript client library in our HTML file.

<script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft.signalr/3.1.0/signalr.min.js"></script>

Next, we can create a simple HTML structure for our chat application:

<!DOCTYPE html>
<html>
<head>
  <title>Chat Application</title>
</head>
<body>
  <div id="messagesList"></div>
  <input type="text" id="userInput" placeholder="Name" />
  <input type="text" id="messageInput" placeholder="Message" />
  <button id="sendButton">Send</button>
</body>
</html>

This basic HTML structure includes a list to display messages, an input for the user's name, an input for the message, and a button to send the message. The next step is to wire up the SignalR connection and handle sending and receiving messages.

Establishing the SignalR Connection

To connect to the SignalR hub, you can use the following JavaScript code:

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chat")
    .build();

connection.on("ReceiveMessage", (user, message) => {
    const msg = document.createElement("div");
    msg.textContent = \`\${user}: \${message}\`;
    document.getElementById("messagesList").appendChild(msg);
});

document.getElementById("sendButton").addEventListener("click", () => {
    const user = document.getElementById("userInput").value;
    const message = document.getElementById("messageInput").value;
    connection.invoke("SendMessage", user, message).catch(err => console.error(err.toString()));
});

connection.start().catch(err => console.error(err.toString()));

This code initializes a new SignalR connection to the /chat URL, which corresponds to the hub we set up earlier. It defines an event handler for the ReceiveMessage event, which updates the chat window when a new message is received. The click event on the send button invokes the SendMessage method on the server with the user's name and message.

Testing the Chat Application

After setting up the client and server-side code, you can run your application and test the chat functionality. Open multiple browser windows or tabs to simulate different users and try sending messages between them. You should see that messages sent from one client appear in all connected clients in real time.

Handling Disconnections

It is important to handle disconnections gracefully. SignalR provides built-in events for connection state changes, which you can use to update the UI or notify users. For instance, you can listen for the onclose event:

connection.onclose(async () => {
  console.log("Connection closed. Attempting to reconnect...");
  await start();
});

async function start() {
  try {
    await connection.start();
    console.log("Connected to SignalR server");
  } catch (err) {
    console.error(err);
    setTimeout(start, 5000);
  }
}

This code attempts to reconnect to the SignalR server if the connection is closed unexpectedly. Implementing such a feature improves the robustness of your chat application.

Edge Cases & Gotchas

When working with SignalR, there are several edge cases and potential pitfalls to be aware of:

Connection Limits: SignalR has a default limit on the number of concurrent connections. Be mindful of this when designing your application, especially if you expect high traffic.
Message Size Limits: Messages sent through SignalR have a maximum size. Large messages may be truncated, so it's advisable to implement a strategy for breaking up large data payloads.
Cross-Origin Requests: If your SignalR server is hosted on a different domain than your client, ensure to configure CORS properly to allow cross-origin requests.

Common Mistakes

One common mistake is not awaiting asynchronous calls in the hub methods, which can lead to unexpected behavior. Always use await with asynchronous methods in your hubs to ensure proper execution order. Additionally, failing to start the SignalR connection before invoking methods will result in errors. Ensure that connection.start() is called and awaited before sending messages.

Performance & Best Practices

Optimizing the performance of your SignalR application involves several best practices:

Use Connection Resiliency: Implement automatic reconnection logic to handle transient failures gracefully.
Minimize Payload Size: Keep messages small and concise. Use compression if necessary, especially for large data.
Scale Out with Backplanes: If your application runs on multiple servers, consider using a backplane like Redis to manage messages across servers efficiently.
Profile Your Application: Use tools like Application Insights or logging to monitor performance and identify bottlenecks in real-time.

Real-World Scenario: Building a Complete Chat Application

Now that we have covered the fundamentals, let's tie everything together by building a complete chat application. Below is the full implementation of the ASP.NET Core chat application using SignalR.

// Program.cs
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
  public static void Main(string[] args)
  {
    CreateHostBuilder(args).Build().Run();
  }

  public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args)
    .ConfigureWebHostDefaults(webBuilder =>
      {
        webBuilder.UseStartup<Startup>();
      });
}

// Startup.cs
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

public class Startup
{
  public void ConfigureServices(IServiceCollection services)
  {
      services.AddSignalR();
  }

  public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
  {
      if (env.IsDevelopment())
      {
          app.UseDeveloperExceptionPage();
      }
      app.UseRouting();

      app.UseEndpoints(endpoints =>
      {
          endpoints.MapHub<ChatHub>("/chat");
      });
  }
}

// ChatHub.cs
using Microsoft.AspNetCore.SignalR;
using System.Threading.Tasks;

public class ChatHub : Hub
{
  public async Task SendMessage(string user, string message)
  {
      await Clients.All.SendAsync("ReceiveMessage", user, message);
  }
}

// index.html
<!DOCTYPE html>
<html>
<head>
  <title>Chat Application</title>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/microsoft.signalr/3.1.0/signalr.min.js"></script></head>
<body>
  <div id="messagesList"></div>
  <input type="text" id="userInput" placeholder="Name" />
  <input type="text" id="messageInput" placeholder="Message" />
  <button id="sendButton">Send</button>
  <script>
const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chat")
    .build();

connection.on("ReceiveMessage", (user, message) => {
    const msg = document.createElement("div");
    msg.textContent = \`\${user}: \${message}\`;
    document.getElementById("messagesList").appendChild(msg);
});

document.getElementById("sendButton").addEventListener("click", () => {
    const user = document.getElementById("userInput").value;
    const message = document.getElementById("messageInput").value;
    connection.invoke("SendMessage", user, message).catch(err => console.error(err.toString()));
});

connection.start().catch(err => console.error(err.toString()));
</script>
</body>
</html>

This complete code implements a basic chat application using SignalR. It includes the server-side configuration for the hub and the client-side JavaScript to send and receive messages. By running this application, you can see real-time chat functionality in action.

Conclusion

SignalR is an essential library for implementing real-time web functionality in ASP.NET Core applications.
Understanding how to set up SignalR, create hubs, and manage client connections is crucial for building interactive applications.
Handling edge cases and optimizing performance will enhance the user experience.
Real-world applications like chat systems can significantly benefit from SignalR's capabilities.
Next steps include exploring advanced features of SignalR, such as group messaging and authentication.