PersistentConnection

Persistent Connections

A PersistentConnection is an IHttpHandler that has an api for exposing a SignalR service over http.

To create a new endpoint. Create a new class that derives from PersistentConnection.

public class MyEndPoint : PersistentConnection 
{
}

To make this endpoint accessible, add a route to Application_Start (or something similar):

using SignalR.Routing;

public void Application_Start() {
    RouteTable.Routes.MapConnecton<MyEndPoint>("echo", "echo/{*operation}");
}

This will expose make /echo a SignalR endpoint.

PersistentConnection API

Task PersistentConnection.OnConnectedAsync(HttpContextBase context, string clientId)

Called when a new connection is made.

• context - The HttpContext associated with this connection.
• clientId - The client id of the new connection.
• NOTE: You can use OnConnected if you just want to do synchronous work and not have to return a Task.

Example

public class MyEndPoint : PersistentConnection 
{
    protected override Task OnConnectedAsync(HttpContextBase context, string clientId)
    {
        return Connection.Broadcast("Client " + clientId + " connected");
    }
}

Task PersistentConnection.OnReceivedAsync(string clientId, string data)

Called when data is received from on the connection.

• clientId - The id of the client that sent the data
• data - The payload received from the client
• NOTE: You can use OnReceived if you just want to do synchronous work and not have to return a Task.

Example

public class MyEndPoint : PersistentConnection 
{
    protected override Task OnReceivedAsync(string clientId, string data) 
    {
        return Connection.Broadcast("Client " + clientId + " sent " + data);   
    }
}

Task PersistentConnection.OnDisconnectAsync(string clientId)

Called when data is received from on the connection.

• clientId - The id of the client that disconnected
• NOTE: You can use OnDisconnect if you just want to do synchronous work and not have to return a Task.

Example

public class MyEndPoint : PersistentConnection 
{
    protected override Task OnDisconnectAsync(string clientId) 
    {
        return Connection.Broadcast("Client " + clientId + " disconncted");   
    }
}

Task PersistentConnection.Send(string clientId, object value)

Sends a message to a specified client.

• clientId - Client id to send the message to
• data - The payload to send
• NOTE: Objects will be JSON serialized

Example

public class MyEndPoint : PersistentConnection 
{
    protected override Task OnReceivedAsync(string clientId, string data) 
    {
        return Send(clientId, data);   
    }
}

Task PersistentConnection.AddToGroup(string clientId, string groupName)

Adds a client to a specified group.

• clientId - client id to add to the group
• groupName - name of the group to add the client to
• NOTE: The task returned from this method does not mean the client was successfully added to the group.

Example

public class MyEndPoint : PersistentConnection 
{
    protected override Task OnReceivedAsync(string clientId, string data) 
    {
        return AddToGroup(clientId, "foo");   
    }
}

Task PersistentConnection.RemoveFromGroup(string clientId, string groupName)

Removes a client from a specified group.

• clientId - client id to remove from the group
• groupName - name of the group to remove the client from
• NOTE: The task returned from this method does not mean the client was successfully added to the group.

Example

public class MyEndPoint : PersistentConnection 
{
    protected override Task OnReceivedAsync(string clientId, string data) 
    {
        return RemoveFromGroup(clientId, "foo");   
    }
}

Task PersistentConnection.SendToGroup(string groupName, object value)

Sends a message to a specified group.

• groupName - name of the group to send the message to
• value - The payload to send
• NOTE: Objects will be JSON serialized

Example

public class MyEndPoint : PersistentConnection 
{
    protected override Task OnReceivedAsync(string clientId, string data) 
    {
        return SendToGroup("foo", data);   
    }
}

IConnection PersistentConnection.Connection

• Gets the IConnection for this PersistentConnection.

IConnection API

Task IConnection.Broadcast(object value)

Broadcasts a message to all on this connection.

• NOTE: the value is JSON serialized

Broadcasting over a connection from outside of a PersistentConnection

Sometimes you have some arbitrary code in an application that you want to be able to notify all clients connected when some event occurs. An example of this might be a background task that sends data at a certain interval.

In these scenarios, you can get an IConnection for a specific persistent connection by calling Connection.GetConnection<T>:

IConnection connection = Connection.GetConnection<MyEndPoint>();

Once you have the connection, you can call Broadcast to send a message to all clients.

NOTE: This API is far from complete and is subject to change.