This document provides an introduction to using the Hubs API for SignalR version 1.1 in JavaScript clients, such as browsers and Windows Store (WinJS) applications.
The SignalR Hubs API enables you to make remote procedure calls (RPCs) from a server to connected clients and from clients to the server. In server code, you define methods that can be called by clients, and you call methods that run on the client. In client code, you define methods that can be called from the server, and you call methods that run on the server. SignalR takes care of all of the client-to-server plumbing for you.
SignalR also offers a lower-level API called Persistent Connections. For an introduction to SignalR, Hubs, and Persistent Connections, or for a tutorial that shows how to build a complete SignalR application, see SignalR - Getting Started.
You can program a JavaScript client to communicate with a SignalR service with or without a proxy that SignalR generates for you. What the proxy does for you is simplify the syntax of the code you use to connect, write methods that the server calls, and call methods on the server.
When you write code to call server methods, the generated proxy enables you to use syntax that looks as though you were executing a local function: you can write serverMethod(arg1, arg2) instead of invoke('serverMethod', arg1, arg2). The generated proxy syntax also enables an immediate and intelligible client-side error if you mistype a server method name. And if you manually create the file that defines the proxies, you can also get IntelliSense support for writing code that calls server methods.
For example, suppose you have the following Hub class on the server:
The following code examples show what JavaScript code looks like for invoking the NewContosoChatMessage method on the server and receiving invocations of the addContosoChatMessageToPage method from the server.
If you want to register multiple event handlers for a client method that the server calls, you can’t use the generated proxy. Otherwise, you can choose to use the generated proxy or not based on your coding preference. If you choose not to use it, you don’t have to reference the “signalr/hubs” URL in a script element in your client code.
Client setup
A JavaScript client requires references to jQuery and the SignalR core JavaScript file. The jQuery version must be 1.6.4 or major later versions, such as 1.7.2, 1.8.2, or 1.9.1. If you decide to use the generated proxy, you also need a reference to the SignalR generated proxy JavaScript file. The following example shows what the references might look like in an HTML page that uses the generated proxy.
These references must be included in this order: jQuery first, SignalR core after that, and SignalR proxies last.
How to reference the dynamically generated proxy
In the preceding example, the reference to the SignalR generated proxy is to dynamically generated JavaScript code, not to a physical file. SignalR creates the JavaScript code for the proxy on the fly and serves it to the client in response to the “/signalr/hubs” URL. If you specified a different base URL for SignalR connections on the server in your MapHubs method, the URL for the dynamically generated proxy file is your custom URL with “/hubs” appended to it.
In an ASP.NET Web Forms application, use ResolveClientUrl for your proxies file reference or register it via the ScriptManager using an app root relative path (starting with a tilde):
As a general rule, use the same method for specifying the “/signalr/hubs” URL that you use for CSS or JavaScript files. If you specify a URL without using a tilde, in some scenarios your application will work correctly when you test in Visual Studio using IIS Express but will fail with a 404 error when you deploy to full IIS. For more information, see Resolving References to Root-Level Resources in Web Servers in Visual Studio for ASP.NET Web Projects on the MSDN site.
When you run a web project in Visual Studio 2012 in debug mode, and if you use Internet Explorer as your browser, you can see the proxy file in Solution Explorer under Script Documents, as shown in the following illustration.
JavaScript generated proxy file in Solution Explorer
To see the contents of the file, double-click hubs. If you are not using Visual Studio 2012 and Internet Explorer, or if you are not in debug mode, you can also get the contents of the file by browsing to the “/signalR/hubs” URL. For example, if your site is running at http://localhost:56699, go to http://localhost:56699/SignalR/hubs in your browser.
How to create a physical file for the SignalR generated proxy
As an alternative to the dynamically generated proxy, you can create a physical file that has the proxy code and reference that file. You might want to do that for control over caching or bundling behavior, or to get IntelliSense when you are coding calls to server methods.
To create a proxy file, perform the following steps:
signalr ghp /path:[path to the .dll that contains your Hub class]
The path to your .dll is typically the bin folder in your project folder.
This command creates a file named server.js in the same folder as signalr.exe.
Put the server.js file in an appropriate folder in your project, rename it as appropriate for your application, and add a reference to it in place of the “signalr/hubs” reference.
How to establish a connection
Before you can establish a connection, you have to create a connection object, create a proxy, and register event handlers for methods that can be called from the server. When the proxy and event handlers are set up, establish the connection by calling the start method.
If you are using the generated proxy, you don’t have to create the connection object in your own code because the generated proxy code does it for you.
[!NOTE] Normally you register event handlers before calling the start method to establish the connection. If you want to register some event handlers after establishing the connection, you can do that, but you must register at least one of your event handler(s) before calling the start method. One reason for this is that there can be many Hubs in an application, but you wouldn’t want to trigger the OnConnected event on every Hub if you are only going to use to one of them. When the connection is established, the presence of a client method on a Hub’s proxy is what tells SignalR to trigger the OnConnected event. If you don’t register any event handlers before calling the start method, you will be able to invoke methods on the Hub, but the Hub’s OnConnected method won’t be called and no client methods will be invoked from the server.
$.connection.hub is the same object that $.hubConnection() creates
As you can see from the examples, when you use the generated proxy, $.connection.hub refers to the connection object. This is the same object that you get by calling $.hubConnection() when you aren’t using the generated proxy. The generated proxy code creates the connection for you by executing the following statement:
Creating a connection in the generated proxy file
When you’re using the generated proxy, you can do anything with $.connection.hub that you can do with a connection object when you’re not using the generated proxy.
Asynchronous execution of the start method
The start method executes asynchronously. It returns a jQuery Deferred object, which means that you can add callback functions by calling methods such as pipe, done, and fail. If you have code that you want to execute after the connection is established, such as a call to a server method, put that code in a callback function or call it from a callback function. The .done callback method is executed after the connection has been established, and after any code that you have in your OnConnected event handler method on the server finishes executing.
If you put the “Now connected” statement from the preceding example as the next line of code after the start method call (not in a .done callback), the console.log line will execute before the connection is established, as shown in the following example:
Wrong way to write code that runs after connection is established
How to establish a cross-domain connection
Typically if the browser loads a page from http://contoso.com, the SignalR connection is in the same domain, at http://contoso.com/signalr. If the page from http://contoso.com makes a connection to http://fabrikam.com/signalr, that is a cross-domain connection. For security reasons, cross-domain connections are disabled by default. To establish a cross-domain connection, make sure that cross-domain connections are enabled on the server, and specify the connection URL when you create the connection object. SignalR will use the appropriate technology for cross-domain connections, such as JSONP or CORS.
On the server, enable cross-domain connections by selecting that option when you call the MapHubs method.
On the client, specify the URL when you create the connection object (without the generated proxy) or before you call the start method (with the generated proxy).
Client code that specifies a cross-domain connection (with the generated proxy)
1: var connection = $.hubConnection('http://fabrikam.com/');
When you use the $.hubConnection constructor, you don’t have to include signalr in the URL because it is added automatically (unless you specify useDefaultUrl as false).
You can create multiple connections to different endpoints.
1: var connection1 = $.hubConnection('http://contoso.com/');
2: var connection2 = $.hubConnection('http://fabrikam.com/');
[!NOTE]
Don’t set jQuery.support.cors to true in your code.
Don’t set jQuery.support.cors to true
SignalR handles the use of JSONP or CORS. Setting jQuery.support.cors to true disables JSONP because it causes SignalR to assume the browser supports CORS.
When you’re connecting to a localhost URL, Internet Explorer 10 won’t consider it a cross-domain connection, so the application will work locally with IE 10 even if you haven’t enabled cross-domain connections on the server.
For information about using cross-domain connections with Internet Explorer 9, see this StackOverflow thread.
Before you establish a connection, you can specify query string parameters or specify the transport method.
How to specify query string parameters
If you want to send data to the server when the client connects, you can add query string parameters to the connection object. The following examples show how to set a query string parameter in client code.
Set a query string value before calling the start method (with the generated proxy)
As part of the process of connecting, a SignalR client normally negotiates with the server to determine the best transport that is supported by both server and client. If you already know which transport you want to use, you can bypass this negotiation process by specifying the transport method when you call the start method.
Client code that specifies the transport method (with the generated proxy)
Each connection object that you create encapsulates information about a connection to a SignalR service that contains one or more Hub classes. To communicate with a Hub class, you use a proxy object which you create yourself (if you’re not using the generated proxy) or which is generated for you.
On the client the proxy name is a camel-cased version of the Hub class name. SignalR automatically makes this change so that JavaScript code can conform to JavaScript conventions.
1: var contosoChatHubProxy = connection.createHubProxy('ContosoChatHub');
How to define methods on the client that the server can call
To define a method that the server can call from a Hub, add an event handler to the Hub proxy by using the client property of the generated proxy, or call the on method if you aren’t using the generated proxy. The parameters can be complex objects.
Add the event handler before you call the start method to establish the connection. (If you want to add event handlers after calling the start method, see the note in How to establish a connection earlier in this document, and use the syntax shown for defining a method without using the generated proxy.)
Method name matching is case-insensitive. For example, Clients.All.addContosoChatMessageToPage on the server will execute AddContosoChatMessageToPage, addContosoChatMessageToPage, or addcontosochatmessagetopage on the client.
Define method on client (with the generated proxy)
To call a server method from the client, use the server property of the generated proxy or the invoke method on the Hub proxy if you aren’t using the generated proxy. The return value or parameters can be complex objects.
Pass in a camel-case version of the method name on the Hub. SignalR automatically makes this change so that JavaScript code can conform to JavaScript conventions.
The following examples show how to call a server method that doesn’t have a return value and how to call a server method that does have a return value.
2: console.log ('Invocation of NewContosoChatMessage succeeded');
3: }).fail(function (error) {
4: console.log('Invocation of NewContosoChatMessage failed. Error: ' + error);
5: });
The preceding examples show how to call a server method that has no return value. The following examples show how to call a server method that has a return value.
SignalR provides the following connection lifetime events that you can handle:
starting: Raised before any data is sent over the connection.
received: Raised when any data is received on the connection. Provides the received data.
connectionSlow: Raised when the client detects a slow or frequently dropping connection.
reconnecting: Raised when the underlying transport begins reconnecting.
reconnected: Raised when the underlying transport has reconnected.
stateChanged: Raised when the connection state changes. Provides the old state and the new state (Connecting, Connected, Reconnecting, or Disconnected).
disconnected: Raised when the connection has disconnected.
For example, if you want to display warning messages when there are connection problems that might cause noticeable delays, handle the connectionSlow event.
Handle the connectionSlow event (with the generated proxy)
The SignalR JavaScript client provides an error event that you can add a handler for. You can also use the fail method to add a handler for errors that result from a server method invocation.
If you don’t explicitly enable detailed error messages on the server, the exception object that SignalR returns after an error contains minimal information about the error. For example, if a call to newContosoChatMessage fails, the error message in the error object contains “There was an error invoking Hub method 'contosoChatHub.newContosoChatMessage'.” Sending detailed error messages to clients in production is not recommended for security reasons, but if you want to enable detailed error messages for troubleshooting purposes, use the following code on the server.
If a method invocation fails, the error event is also raised, so your code in the error method handler and in the .fail method callback would execute.
How to enable client-side logging
To enable client-side logging on a connection, set the logging property on the connection object before you call the start method to establish the connection.
To see the logs, open your browser’s developer tools and go to the Console tab. For a tutorial that shows step-by-step instructions and screen shots that show how to do this, see Server Broadcast with ASP.NET Signalr - Enable Logging.
)