ASP.NET Core SignalR JavaScript Client

This document provides a comprehensive guide to using the ASP.NET Core SignalR JavaScript client to build real-time web applications. SignalR allows you to add rich, real-time web functionality to your applications, such as live feeds, notifications, and collaborative tools.

Getting Started

To use the SignalR JavaScript client, you first need to include the SignalR JavaScript library in your project. You can do this via a CDN or by installing it using npm or Yarn.

Using a CDN

Add the following script tag to your HTML file:

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

Using npm or Yarn

Install the SignalR client package:

npm install @microsoft/signalr

Or using Yarn:

yarn add @microsoft/signalr

Then, import it into your JavaScript code:

import * as signalR from "@microsoft/signalr";

Connecting to a Hub

Once the library is included, you can create a connection to your SignalR hub. A hub is a pipeline that lets you send messages to and receive from clients. The connection URL typically points to your hub endpoint.

const connection = new signalR.HubConnectionBuilder()
    .withUrl("/myHub") // Replace with your actual hub URL
    .build();

connection.start().then(() => {
    console.log("SignalR Connected!");
}).catch(err => console.error('Connection failed: ', err));

Sending Messages

You can send messages to the server by invoking methods on the hub.

connection.invoke("SendMessage", "Hello from JavaScript!").catch(err => console.error('Error sending message: ', err));

The first argument to invoke is the name of the hub method on the server, followed by any arguments that method expects.

Receiving Messages

To receive messages from the server, you can use the on method to register a handler for specific hub methods.

connection.on("ReceiveMessage", (user, message) => {
    console.log(`Message from ${user}: ${message}`);
    // Update your UI here
    const msgList = document.getElementById("messageList");
    const li = document.createElement("li");
    li.textContent = `${user}: ${message}`;
    msgList.appendChild(li);
});

Error Handling

SignalR provides mechanisms to handle connection errors and re-connections.

connection.onclose(error => {
    console.error("Connection closed: ", error);
    // Attempt to reconnect or inform the user
    setTimeout(() => connection.start(), 5000); // Reconnect after 5 seconds
});

You can also handle errors that occur during message invocation or reception.

Advanced Scenarios

Negotiation and Transports

SignalR uses a negotiation process to determine the best available transport (like WebSockets or Server-Sent Events) for communication. You can configure transport preferences if needed, though the default behavior is generally optimal.

Hub Lifetime Management

Managing the lifecycle of the SignalR connection is crucial. Ensure you start the connection when needed and stop it when the user navigates away or the application is closing to free up resources.

// To stop the connection
// connection.stop().then(() => {
//     console.log("SignalR connection stopped.");
// });

Groups

SignalR supports groups, allowing you to broadcast messages to subsets of clients. Server-side logic will manage group membership.

Authentication

For secure communication, integrate SignalR with your application's authentication system. This typically involves passing an authentication token in the withUrl call.

// Example with an access token
const token = "your_jwt_token"; // Get this from your auth system
const connection = new signalR.HubConnectionBuilder()
    .withUrl("/myHub", { accessTokenFactory: () => token })
    .build();

Offline Scenarios

Consider how your application will behave when the connection is lost. Implement UI feedback and retry mechanisms to provide a seamless user experience.