ASP.NET SignalR 2.x JavaScript Client

Common errors

• Uncaught TypeError: $(...).hubConnection is not a function

  cause The jQuery SignalR plugin was loaded before jQuery, or jQuery was not loaded at all.
  fix Ensure jQuery is loaded *before* `jquery.signalr.js` in your HTML or bundler configuration.

• Uncaught ReferenceError: jQuery is not defined

  cause jQuery script was not loaded or was loaded incorrectly.
  fix Verify the `<script>` tag for jQuery is present, points to the correct path, and is loaded before any scripts that depend on it.

• WebSocket connection to 'ws://...' failed: Error during WebSocket handshake: Unexpected response code: 404

  cause The SignalR server endpoint or specific hub could not be found, often due to incorrect URL or server-side configuration.
  fix Check the URL provided to `$.connection.hub.url` (or the default `/signalr` route). Ensure your ASP.NET SignalR server is running and the hub route is correctly mapped (`RouteTable.Routes.MapHubs();`).

• Error: SignalR: Connection has not been started. Call .start() before using any of the hubs.

  cause Attempting to invoke a server method or perform other connection actions before `$.connection.hub.start()` has successfully completed.
  fix Ensure all client-side hub invocations (e.g., `hubConnection.invoke()`) and other connection-dependent logic are placed within the `.done()` callback of `$.connection.hub.start()`.

Warnings

• breaking This `signalr` package is for the **legacy ASP.NET SignalR 2.x** (targeting .NET Framework) and is NOT compatible with ASP.NET Core SignalR. Attempting to connect this client to an ASP.NET Core SignalR server will fail. The modern client for ASP.NET Core SignalR is found under the `@microsoft/signalr` npm package.
  Fix: For ASP.NET Core applications, use the `@microsoft/signalr` package. For ASP.NET (Full Framework) applications, ensure your server is configured for ASP.NET SignalR 2.x.
• gotcha This SignalR client requires jQuery to function. It operates as a jQuery plugin, extending the global `jQuery` or `$` object. Loading jQuery is a mandatory prerequisite, and it must be loaded *before* the `jquery.signalr.js` script.
  Fix: Ensure `jQuery` is loaded in your HTML (`<script src=".../jquery.js"></script>`) or bundled correctly before `jquery.signalr.js` is loaded. Missing jQuery will result in `TypeError: $(...).hubConnection is not a function`.
• gotcha The `2.3.0` release incremented the minor version number but explicitly stated it contained 'no new features' and should be considered a 'patch release'. This diverges from standard semantic versioning expectations, where a minor version implies new features.
  Fix: Be aware that minor version increments in this package's history do not always signify new features; always check release notes for actual changes.
• gotcha To interact with server-side hubs, your application must load the auto-generated `/signalr/hubs` script from your ASP.NET SignalR server. This script provides the client-side proxies for your server's hubs (e.g., `$.connection.myHub`). Without it, `$.connection` will not contain your hub definitions.
  Fix: Include `<script src="http://your-server-address/signalr/hubs"></script>` after loading jQuery and `jquery.signalr.js`. Ensure your ASP.NET SignalR server is running and the `/signalr` route is correctly configured.

Install

• npm install signalr npm
• yarn add signalr yarn
• pnpm add signalr pnpm

Imports

• jQuery
  wrong:

  import { $ } from 'jquery'; // While technically possible, SignalR expects global `jQuery` or `$`

  correct:

  import jQuery from 'jquery'; // Or ensure global jQuery is loaded via script tag

  The `signalr` client operates as a jQuery plugin. Ensure jQuery is loaded *before* the SignalR client. In a modern bundler, you might `import 'jquery'` for its side effects, followed by `import 'signalr'`.
• $.hubConnection
  wrong:

  import { hubConnection } from 'signalr'; // This package is not an ES module with named exports.

  correct:

  import 'jquery'; import 'signalr'; // Then `$.hubConnection` is available globally or via `jQuery.hubConnection`

  After jQuery and the SignalR client script are loaded, the `hubConnection` factory becomes available as a method on the global jQuery object. There is no direct ES module import for `hubConnection` from `signalr`.
• $.connection
  wrong:

  import { connection } from 'signalr'; // This package is not an ES module with named exports.

  correct:

  import 'jquery'; import 'signalr'; // Then ensure /signalr/hubs is loaded; `$.connection` becomes available

  This object is used to access proxies for server-side hubs. It becomes available on the global jQuery object after the SignalR client and the `signalr/hubs` script (auto-generated by the ASP.NET SignalR server) are loaded in the correct order.

Quickstart

This example demonstrates how to load the SignalR client, establish a connection to an ASP.NET SignalR server, define a client-side method, and invoke a server-side method for basic real-time communication within an HTML page.

<!-- index.html (full example demonstrating loading order) -->
<!DOCTYPE html>
<html>
<head>
    <title>SignalR Client Example</title>
</head>
<body>
    <div id="discussion"></div>
    <input type="text" id="message" placeholder="Enter message"/>
    <input type="button" id="sendmessage" value="Send" />

    <!-- 1. Ensure jQuery is loaded first -->
    <script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.7.1.min.js"></script>
    <!-- 2. Then the SignalR client -->
    <script src="https://ajax.aspnetcdn.com/ajax/signalr/jquery.signalr-2.4.3.min.js"></script>
    <!-- 3. Then the auto-generated hub proxies from your server -->
    <!-- This URL MUST point to your ASP.NET SignalR server's hubs endpoint -->
    <script src="http://localhost:5000/signalr/hubs"></script>

    <script type="text/javascript">
        $(function () {
            console.log("jQuery and SignalR client scripts loaded.");

            // $.connection contains proxies for server-side hubs (e.g., $.connection.chatHub).
            // The /signalr/hubs script makes this available.
            if ($.connection && $.connection.hub) {
                const hubConnection = $.connection.hub; // The main SignalR connection object

                // Define a client-side method that the server can call
                hubConnection.client.addMessage = function (name, message) {
                    console.log(`Server called addMessage: ${name}: ${message}`);
                    $('<li>').text(`${name}: ${message}`).appendTo('#discussion');
                };

                // Start the connection to the SignalR server
                hubConnection.start()
                    .done(function () {
                        console.log("Connected to SignalR hub. Connection ID: " + hubConnection.id);
                        $('#sendmessage').click(function () {
                            const message = $('#message').val();
                            if (message) {
                                // Invoke a server-side method. 'Send' is a common method name.
                                // 'ChatHub' is the name of your server-side hub class.
                                // Arguments follow the method name.
                                hubConnection.invoke('Send', 'ClientUser', message)
                                    .fail(function(error) {
                                        console.error('Error invoking server method:', error);
                                    });
                                $('#message').val('');
                            }
                        });
                    })
                    .fail(function (error) {
                        console.error("Could not connect to SignalR hub: " + error);
                    });
            } else {
                console.warn("SignalR client or hub proxies not fully loaded. Check script loading order and server /signalr/hubs endpoint.");
            }
        });
    </script>
</body>
</html>