Connection lifetime terminology and scenarios

Timeout and keepalive settings

How to notify the user about disconnections

How to continuously reconnect

How to disconnect a client in server code

Detecting the reason for a disconnection

Links to API Reference topics are to the .NET 4.5 version of the API. If you're using .NET 4, see the .NET 4 version of the API topics .

Connection lifetime terminology and scenarios

The OnReconnected event handler in a SignalR Hub can execute directly after OnConnected but not after OnDisconnected for a given client. The reason you can have a reconnection without a disconnection is that there are several ways in which the word "connection" is used in SignalR.

SignalR connections, transport connections, and physical connections

This article will differentiate between SignalR connections , transport connections , and physical connections :

ConnectionSlow client event.

Raised when a preset proportion of the keepalive timeout period has passed since the last message or keepalive ping was received. The default keepalive timeout warning period is 2/3 of the keepalive timeout. The keepalive timeout is 20 seconds, so the warning occurs at about 13 seconds.

By default, the server sends keepalive pings every 10 seconds, and the client checks for keepalive pings about every 2 seconds (one third of the difference between the keepalive timeout value and the keepalive timeout warning value).

If the transport API becomes aware of a disconnection, SignalR might be informed of the disconnection before the keepalive timeout warning period passes. In that case, the ConnectionSlow event would not be raised, and SignalR would go directly to the Reconnecting event.

Reconnecting client event.

Raised when (a) the transport API detects that the connection is lost, or (b) the keepalive timeout period has passed since the last message or keepalive ping was received. The SignalR client code begins trying to reconnect. You can handle this event if you want your application to take some action when a transport connection is lost. The default keepalive timeout period is currently 20 seconds.

If your client code tries to call a Hub method while SignalR is in reconnecting mode, SignalR will try to send the command. Most of the time, such attempts will fail, but in some circumstances they might succeed. For the server-sent events, forever frame, and long polling transports, SignalR uses two communication channels, one that the client uses to send messages and one that it uses to receive messages. The channel used for receiving is the permanently open one, and that's the one that is closed when the physical connection is interrupted. The channel used for sending remains available, so if physical connectivity is restored, a method call from client to server might be successful before the receive channel is re-established. The return value would not be received until SignalR re-opens the channel used for receiving.

Reconnected client event.

Raised when the transport connection is reestablished. The OnReconnected event handler in the Hub executes.

Closed client event ( disconnected event in JavaScript).

Raised when the disconnect timeout period expires while the SignalR client code is trying to reconnect after losing the transport connection. The default disconnect timeout is 30 seconds. (This event is also raised when the connection ends because the Stop method is called.)

Transport connection interruptions that are not detected by the transport API and don't delay the reception of keepalive pings from the server for longer than the keepalive timeout warning period might not cause any connection lifetime events to be raised.

Some network environments deliberately close idle connections, and another function of the keepalive packets is to help prevent this by letting these networks know that a SignalR connection is in use. In extreme cases the default frequency of keepalive pings might not be enough to prevent closed connections. In that case you can configure keepalive pings to be sent more often. For more information, see Timeout and keepalive settings later in this topic.

Important : The sequence of events described here is not guaranteed. SignalR makes every attempt to raise connection lifetime events in a predictable manner according to this scheme, but there are many variations of network events and many ways in which underlying communications frameworks such as transport APIs handle them. For example, the Reconnected event might not be raised when the client reconnects, or the OnConnected handler on the server might run when the attempt to establish a connection is unsuccessful. This topic describes only the effects that would normally be produced by certain typical circumstances.

Client disconnection scenarios

In a browser client, the SignalR client code that maintains a SignalR connection runs in the JavaScript context of a web page. That's why the SignalR connection has to end when you navigate from one page to another, and that's why you have multiple connections with multiple connection IDs if you connect from multiple browser windows or tabs. When the user closes a browser window or tab, or navigates to a new page or refreshes the page, the SignalR connection immediately ends because SignalR client code handles that browser event for you and calls the Stop method. In these scenarios, or in any client platform when your application calls the Stop method, the OnDisconnected event handler executes immediately on the server and the client raises the Closed event (the event is named disconnected in JavaScript).

If a client application or the computer that it's running on crashes or goes to sleep (for example, when the user closes the laptop), the server is not informed about what happened. As far as the server knows, the loss of the client might be due to connectivity interruption and the client might be trying to reconnect. Therefore, in these scenarios the server waits to give the client a chance to reconnect, and OnDisconnected does not execute until the disconnect timeout period expires (about 30 seconds by default). The following diagram illustrates this scenario.

Server disconnection scenarios

When a server goes offline -- it reboots, fails, the app domain recycles, etc. -- the result might be similar to a lost connection, or the transport API and SignalR might know immediately that the server is gone, and SignalR might begin trying to reconnect without raising the ConnectionSlow event. If the client goes into reconnecting mode, and if the server recovers or restarts or a new server is brought online before the disconnect timeout period expires, the client will reconnect to the restored or new server. In that case, the SignalR connection continues on the client and the Reconnected event is raised. On the first server, OnDisconnected is never executed, and on the new server, OnReconnected is executed although OnConnected was never executed for that client on that server before. (The effect is the same if the client reconnects to the same server after a reboot or app domain recycle, because when the server restarts it has no memory of prior connection activity.) The following diagram assumes that the transport API becomes aware of the lost connection immediately, so the ConnectionSlow event is not raised.

If a server does not become available within the disconnect timeout period, the SignalR connection ends. In this scenario, the Closed event ( disconnected in JavaScript clients) is raised on the client but OnDisconnected is never called on the server. The following diagram assumes that the transport API does not become aware of the lost connection, so it is detected by SignalR keepalive functionality and the ConnectionSlow event is raised.

Timeout and keepalive settings

The default ConnectionTimeout , DisconnectTimeout , and KeepAlive values are appropriate for most scenarios but can be changed if your environment has special needs. For example, if your network environment closes connections that are idle for 5 seconds, you might have to decrease the keepalive value.

ConnectionTimeout

This setting represents the amount of time to leave a transport connection open and waiting for a response before closing it and opening a new connection. The default value is 110 seconds.

This setting applies only when keepalive functionality is disabled, which normally applies only to the long polling transport. The following diagram illustrates the effect of this setting on a long polling transport connection.

DisconnectTimeout

This setting represents the amount of time to wait after a transport connection is lost before raising the Disconnected event. The default value is 30 seconds. When you set DisconnectTimeout , KeepAlive is automatically set to 1/3 of the DisconnectTimeout value.

KeepAlive

This setting represents the amount of time to wait before sending a keepalive packet over an idle connection. The default value is 10 seconds. This value must not be more than 1/3 of the DisconnectTimeout value.

If you want to set both DisconnectTimeout and KeepAlive , set KeepAlive after DisconnectTimeout . Otherwise your KeepAlive setting will be overwritten when DisconnectTimeout automatically sets KeepAlive to 1/3 of the timeout value.

If you want to disable keepalive functionality, set KeepAlive to null. Keepalive functionality is automatically disabled for the long polling transport.

How to change timeout and keepalive settings

To change the default values for these settings, set them in Application_Start in your Global.asax file, as shown in the following example. The values shown in the sample code are the same as the default values.

protected void Application_Start(object sender, EventArgs e)
    // Make long polling connections wait a maximum of 110 seconds for a
    // response. When that time expires, trigger a timeout command and
    // make the client reconnect.
    GlobalHost.Configuration.ConnectionTimeout = TimeSpan.FromSeconds(110);
    // Wait a maximum of 30 seconds after a transport connection is lost
    // before raising the Disconnected event to terminate the SignalR connection.
    GlobalHost.Configuration.DisconnectTimeout = TimeSpan.FromSeconds(30);
    // For transports other than long polling, send a keepalive packet every
    // 10 seconds. 
    // This value must be no more than 1/3 of the DisconnectTimeout value.
    GlobalHost.Configuration.KeepAlive = TimeSpan.FromSeconds(10);
    RouteTable.Routes.MapHubs();
How to notify the user about disconnections
In some applications you might want to display a message to the user when there are connectivity problems. You have several options for how and when to do this. The following code samples are for a JavaScript client using the generated proxy.
Handle the connectionSlow event to display a message as soon as SignalR is aware of connection problems, before it goes into reconnecting mode.
$.connection.hub.connectionSlow(function() {
    notifyUserOfConnectionProblem(); // Your function to notify user.
Handle the reconnecting event to display a message when SignalR is aware of a disconnection and is going into reconnecting mode.
$.connection.hub.reconnecting(function() {
    notifyUserOfTryingToReconnect(); // Your function to notify user.
Handle the disconnected event to display a message when an attempt to reconnect has timed out. In this scenario, the only way to re-establish a connection with the server again is to restart the SignalR connection by calling the Start method, which will create a new connection ID. The following code sample uses a flag to make sure that you issue the notification only after a reconnecting timeout, not after a normal end to the SignalR connection caused by calling the Stop method.
var tryingToReconnect = false;
$.connection.hub.reconnecting(function() {
    tryingToReconnect = true;
$.connection.hub.reconnected(function() {
    tryingToReconnect = false;
$.connection.hub.disconnected(function() {
    if(tryingToReconnect) {
        notifyUserOfDisconnect(); // Your function to notify user.
How to continuously reconnect
In some applications you might want to automatically re-establish a connection after it has been lost and the attempt to reconnect has timed out. To do that, you can call the Start method from your Closed event handler (disconnected event handler on JavaScript clients). You might want to wait a period of time before calling Start in order to avoid doing this too frequently when the server or the physical connection are unavailable. The following code sample is for a JavaScript client using the generated proxy.
$.connection.hub.disconnected(function() {
   setTimeout(function() {
       $.connection.hub.start();
   }, 5000); // Restart connection after 5 seconds.
A potential problem to be aware of in mobile clients is that continuous reconnection attempts when the server or physical connection isn't available could cause unnecessary battery drain.
How to disconnect a client in server code
SignalR version 2 does not have a built-in server API for disconnecting clients. There are plans for adding this functionality in the future. In the current SignalR release, the simplest way to disconnect a client from the server is to implement a disconnect method on the client and call that method from the server. The following code sample shows a disconnect method for a JavaScript client using the generated proxy.
var myHubProxy = $.connection.myHub
myHubProxy.client.stopClient = function() {
    $.connection.hub.stop();
Warning
Security - Neither this method for disconnecting clients nor the proposed built-in API will address the scenario of hacked clients that are running malicious code, since the clients could reconnect or the hacked code might remove the stopClient method or change what it does. The appropriate place to implement stateful denial-of-service (DOS) protection is not in the framework or the server layer, but rather in front-end infrastructure.
Detecting the reason for a disconnection
SignalR 2.1 adds an overload to the server OnDisconnect event that indicates if the client deliberately disconnected rather than timing out. The StopCalled parameter is true if the client explicitly closed the connection. In JavaScript, if a server error led the client to disconnect, the error information will be passed to the client as $.connection.hub.lastError.
C# server code: stopCalled parameter
public override System.Threading.Tasks.Task OnDisconnected(bool stopCalled)
    if (stopCalled)
        Console.WriteLine(String.Format("Client {0} explicitly closed the connection.", Context.ConnectionId));
        Console.WriteLine(String.Format("Client {0} timed out .", Context.ConnectionId));
    return base.OnDisconnected(stopCalled);
JavaScript client code: accessing lastError in the disconnect event.
$.connection.hub.disconnected(function () {
    if ($.connection.hub.lastError) 
        { alert("Disconnected. Reason: " +  $.connection.hub.lastError.message); }