As we know, in all the methods of the PersistentConnection class that allow us to take control when an important event takes place (connection, disconnection, data arrival, and so on) we have an IRequest type parameter available that allows us to obtain information from the request, where, among other things, we can get the authenticated user.

Therefore, a possibility when controlling access to specific functions within a persistent connection would be to query this information and act accordingly.

protected override Task OnReceived(IRequest request,
                                   string connectionId, string data)
{
   if (request.User==null || !request.User.Identity.IsAuthenticated)
       throw new NotAuthorizedException();
    ...
}

When this code is common to all operations relative to the PersistentConnection class that we are implementing, it is recommended that we override the AuthorizeRequest method that will be invoked by SignalR before passing control to the other events. This method receives a parameter of the IRequest type with information about the incoming request and returns a simple Boolean indicating whether access is allowed or not:

protected override bool AuthorizeRequest(IRequest request)
{
   return (request.User!=null &&
           request.User.Identity.IsAuthenticated);
}

Obviously, the access criteria can be more complex—for example, requiring the checking of other information included in the request, access times, role membership, or whatever we need for our application.

In this case, we can control access to specific actions or complete hubs by using a mechanism that is similar to the one we already have in other ASP.NET technologies: the Authorize attribute.

A hub method decorated with this attribute causes it to be accessible only to users authenticated in the application:

[Authorize]
public Task SecureBroadcast(string message)
{
    return Clients.All.Message(message);
}

Likewise, if we want to apply this control to all methods of the hub, we just have to apply it at class level:

[Authorize]
public class SecureEchoHub : Hub
{
    ...
}

It is very important to take into account that this is a different attribute than the one we use in Web API or in ASP.NET MVC, so we must be careful not to include incorrect namespaces when we are using it. If we apply the Web API [Authorize] attribute (defined in System.Web.Http) on a hub, it will simply not take effect. In Figure 9-1, we can see that when [Authorize] is included, Visual Studio suggests the inclusion of three different namespaces, where attributes with this name are defined.

Figure 9-1. Namespaces available when including the Authorize attribute in our applications.

If we want this check to be performed on all the hubs of our application, we can set it globally during system initialization:

// Inserts an AuthorizeModule in the pipeline
GlobalHost.HubPipeline.RequireAuthentication();

When decorating our actions or hubs, we can be more explicit and not leave it at a mere check of user authentication status. The following code shows how to allow access to the method to specific users of the system:

[Authorize(Users="fmercury,mjackson,fsinatra")]
public void Sing(string song)
{
    // ...
}

We also have the ability to restrict it to certain application roles:

[Authorize(Roles= "greatsingers")]
public void Sing(string song)
{
    // ...
}

Unlike its Web API and MVC counterparts, the SignalR Authorize attribute has an additional parameter that makes sense only when applied at hub level:

[Authorize(RequireOutgoing=false, Roles="admin")]
public class SecureEchoHub : Hub
{
    ...
    public Task SecureBroadcast(string message)
    {
        return Clients.All.Message(message);
    }
}

In the preceding example, only authenticated users belonging to the “admin” role can invoke hub methods such as SecureBroadcast(), but by setting the RequireOutgoing parameter to false, we are indicating that no authorization is required to connect to the hub and receive messages sent from it. Therefore, thanks to this mechanism, we can have hubs to which anonymous clients connect in “passive mode” only to receive messages, whereas other privileged users would be able to invoke their methods.

We can also extend the Authorize attribute to implement our own authorization logic. For example, the following attribute is used to allow passage to users whose name contains the character “a”:

public class OnlyIfUsernameContainsAAttribute: AuthorizeAttribute
{
    protected override bool UserAuthorized(IPrincipal user)
    {
       return base.UserAuthorized(user)
              && user.Identity.Name.ToLowerInvariant().Contains("a");
    }
}
// Usage in a Hub method:
[OnlyIfUsernameContainsA]
public void DoSomething()
{
    ...
}

Or we could ensure that the connection is made using SSL, as in the following example:

public class OnlySslAttribute: AuthorizeAttribute
{
    public override bool AuthorizeHubConnection(
                HubDescriptor hubDescriptor, IRequest request)
    {
        return request.Url.Scheme == "https"
             && base.AuthorizeHubConnection(hubDescriptor, request);
    }
}

We have seen how to protect access to persistent connections or to methods and hubs on the server side using diverse techniques, but basically, all of them rely on the assumption that the execution context will contain information about the connected user. That is, we assume that some component previously executed in the pipeline will have correctly set the User property of the context of the request, that information such as User.Identity.Name or User.Identity.IsAuthenticated will be available, and that we will be able to determine their role membership with the familiar User.IsInRole() method.

Although at first it might seem as though the SignalR framework itself is the one in charge of establishing identity in its requests to ensure that information about the active user reaches the application, this is not the case; the ones that do this dirty work are found further down the technology stack—see Figure 9-2—at OWIN middleware level.

Figure 9-2. The architecture of OWIN systems.

This way, these modules are completely reusable across projects and systems. For example, the module responsible for managing authorization through cookies is the same one for SignalR and Web API, Nancy, or FubuMVC. In fact, the implementation of authentication and authorization management middleware modules is not even found in the SignalR project, but in Katana.

Currently, the Katana project includes the following modules, although more are expected to come in the future:

When we are in a pure web environment, the way authentication information reaches the server side and our hubs is quite straightforward, because we are normally in the same application.

For example, if we are using traditional cookie-based security and have accessed a page to log in to the website, those same cookies that it sends us upon successful authentication and which keep our session open on the server will travel in all requests to it, including those made by SignalR to open the virtual connection.

The Microsoft.Owin.Security.Cookies middleware, in charge of managing this security mechanism, will capture the requests, verify that they contain the authentication token, and set the user information obtained from said user in the context of the requests. From there, the request will continue to rise through the various modules, and when it reaches SignalR, the user information will be available and ready to be used.

However, when it comes to clients that are external to the server runtime environment, such as .NET generic clients or WinRT applications, we need to use other alternatives based on the mechanisms that SignalR client libraries offer to append information to requests, such as cookies or HTTP headers, to send data about the user. Obviously, in this case, the server side should implement the corresponding code to obtain this information and convert it to processable authentication information. For example, the following code adds an authentication token to the connection in the form of a cookie:

var connection = new HubConnection("http://localhost:3421");
string token = GetAuthToken();   // Gets an auth token
                                 // from anywhere
// Attach the token to the connection
connection.CookieContainer = new CookieContainer();
connection.CookieContainer.Add(new Cookie("Token", token));

After we have generated the token and attached the cookie with it to the connection to the hub, all requests made in that context will be accompanied by said cookie.

In fact, a frequently implemented technique is to get the token via a previous call to the server, which returns it in a cookie. When we obtain the cookie, we would use it for the SignalR connections, as shown in Figure 9-3.

Applying this technique is quite simple, because all we need is the web service that we would invoke from the client side. This web service would check whether the supplied credentials are valid and, if so, return the cookie proving that the user was authenticated successfully.

Figure 9-3. Getting authentication cookies via previous request.

Now we will see an example implementation of this authentication based on the cookie-based security module of the Katana project: Microsoft.Owin.Security.Cookies. Thus, the first thing we would have to do is install the package containing the module on our server:

PM> install-package Microsoft.Owin.Security.Cookies

Next we would include it in the OWIN process flow during application startup:

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
        ...
        var options = new CookieAuthenticationOptions()
        {
            CookieName = "Token"
        };
        app.UseCookieAuthentication(options);
        ...
    }
}

The UseCookieAuthentication() extender enters the middleware into the OWIN pipeline, supplying it a configuration object, which, in this case, we use only to tell the module the name of the cookie where it must enter the authentication information. This name is important because we will need to recover the information from the client side.

At this point, our system is ready both to generate authentication cookies and to process them in every call, modifying the user of the request context based on the information in the token. Now we are going to implement the web service that will receive the user’s credentials and, based on them, return the corresponding cookie:

public class CustomLoginMiddleware : OwinMiddleware
{
    public CustomLoginMiddleware(OwinMiddleware next)
        : base(next)
    {
    }
    public override async Task Invoke(IOwinContext context)
    {
        var path = context.Request.Path.Value.ToLower();
        if (context.Request.Method == "POST"
            && path.EndsWith("/account/remotelogin"))
        {
            var form = await context.Request.ReadFormAsync();
            var userName = form["username"];
            var password = form["password"];
            if (validate(userName, password))
            {
                var identity = new ClaimsIdentity(
                    CookieAuthenticationDefaults.AuthenticationType
                );
                identity.AddClaim(
                    new Claim(ClaimTypes.Name, userName)
                );
                identity.AddClaim(
                    new Claim(ClaimTypes.Role, "user")
                );
                context.Authentication.SignIn(identity);
                context.Response.StatusCode = 200;
                context.Response.ReasonPhrase = "Authorized";
            }
            else
            {
                context.Response.StatusCode = 401;
                context.Response.ReasonPhrase = "Unauthorized";
            }
            return;
        }
        await Next.Invoke(context);
    }
    private bool validate(string username, string password)
    {
        return true; // Just for brevity
    }
}

As usual in custom middleware modules, the class inherits from OwinMiddleware, which basically imposes the following two obligations on us:

Inside the module, the only thing that is done is the checking of the validity of the credentials (it is very simplified in this case) and, if they are valid, invoking the Authentication.SignIn() method of the context, supplying it a ClaimsIdentity object with user information, generating the cookie that will accompany the response to the request.

This module would be installed on the startup code and also in the pipeline. We already include the complete code of the Configuration() method, where you can see the SignalR mapping at the end:

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
        var options = new CookieAuthenticationOptions()
        {
            CookieName = "Token"
        };
        app.UseCookieAuthentication(options);
        app.Use<CustomLoginMiddleware>();
        app.MapSignalR();
    }
}

After we have done this, our server will be able to respond to POST requests directed to the URL /account/remotelogin. Let’s now see how we can invoke this service from the client side to get the cookie and attach it to the SignalR connection.

First, let’s look at a possible implementation of a method that takes as arguments the URL of the authentication service and the credentials and that is used to obtain and return the value of the cookie called “Token” (note that this name is the one that we previously set on the server side):

private static async Task<Cookie> GetAuthCookie(
          string loginUrl, string user, string pass)
{
    var postData = string.Format(
                            "username={0}&password={1}",
                             user, pass
    );
    var httpHandler = new HttpClientHandler();
    httpHandler.CookieContainer = new CookieContainer();
    using (var httpClient = new HttpClient(httpHandler))
    {
        var response = await httpClient.PostAsync(
            loginUrl,
            new StringContent(postData, Encoding.UTF8,
                      "application/x-www-form-urlencoded"
            )
        );
        var cookies = httpHandler.CookieContainer
                                 .GetCookies(new Uri(loginUrl));
        return cookies["Token"];
    }
}

With appropriate adaptations, this method could be consumed from any type of .NET system. The following example demonstrates its use from a console application that acts as a SignalR client. In the code, you can see how the cookie is obtained with the authentication token from the server and is attached to the hub connection:

var host = "http://localhost:5432";
var loginUrl = "/account/remotelogin";
var authCookie = GetAuthCookie(loginUrl, username, password).Result;
if (authCookie == null)
{
    Console.WriteLine("Impossible to get the auth token.");
    return;
}
var connection = new HubConnection(host);
connection.CookieContainer = new CookieContainer();
connection.CookieContainer.Add(authCookie);
var proxy = connection.CreateHubProxy("EchoHub");
...
connection.Start().Wait();
proxy.Invoke("SendPrivateMessage", "Hi, I'm authenticated!");
...

The same authentication middleware, being ultimately a service, can also be invoked from a web client—for example, by an AJAX call in JavaScript, or even (with some modifications in the component) as a destination for a login form. The following code shows how to deliver the cookie to the client by using AJAX. All subsequent requests to the service will include this cookie:

$("#login").click(function () {
    var u = $("#username").val();
    var p = $("#password").val();
    $.post("/account/login", { username: u, password: p })
        .done(function () {
            // The auth cookie will be attached
            // to the following request so I'll be authenticated
            location.href = "/chat/index";
        });
    return true;
});

If we tried to connect to a hub such as the preceding one, we would get at best a 500 error indicating that there is no constructor without parameters for the hub. This is only natural, because for all this to work, we need someone to supply the dependencies to the hub constructor. Who better than the Dependency Resolver to take care of that?

Remember that a few pages ago we were checking the calls that were internally made to the Dependency Resolver, and when we obtained the ones corresponding to the execution of a hub, we could see that SignalR asked the Dependency Resolver for an instance of the hub class, but a null value was returned:

...
*** Requested type IServerCommandHandler, provided: ServerCommandHandler
*** Requested type IAssemblyLocator, provided: EnumerableOfAssemblyLocator
*** Requested type ITransportHeartbeat, provided: TransportHeartbeat
*** Requested type CustomerHub, provided: null

All that we would need would be to register in the Dependency Resolver an association between the data type requested (CustomerHub) and the action that would create the instance. This action is the point from which the constructor would be invoked, supplying it the required dependencies.

The code to enter in the application startup would be the following:

GlobalHost.DependencyResolver.Register(
    typeof(CustomerHub),
    () => new CustomerHub(
                new CustomerRepository(),
                new MailManager()
          )
);

This way, every time SignalR needs a CustomerHub type object—which will happen on every call or client interaction—it will request it from the Dependency Resolver, which will execute the lambda function and return the created instance.

If we work with persistent connections instead of hubs, we can get exactly the same result by applying the same techniques. These objects, of types descending from PersistentConnection, are also requested from the Dependency Resolver, so we can capture that moment and supply an object with the dependencies already satisfied:

// Configuration:
GlobalHost.DependencyResolver.Register(
    typeof(MyConnection),
    () => new MyConnection(
                new MyDependency()
          )
);
// Persistent Connection
public class MyConnection: PersistentConnection
{
    private IMyDependency _dependency;
    public MyConnection(IMyDependency dependency)
    {
        _dependency = dependency;
    }
    ...
}

However, the latter case is not quite recommended, and we must be very careful with its use, because the life of a PersistentConnection can be long (depending on the transport used, the instance could even be active throughout the whole time the user is connected), and if we create dependencies that use valuable resources, these might be unavailable for other uses. In these cases, it is better to opt for a close control of the lifetime of such dependencies—for example, by obtaining them through the Service Locator and delimiting their use with a using block to ensure their release when they are no longer needed.

Sometimes dependencies use external resources that have to be released. For example, a hub could use an Entity Framework data context to persist information in the database, and we should always ensure that both it and (hence) the underlying connection it uses have been closed and released.

Currently, SignalR provides no mechanism to automatically release dependencies (or, for example, those that implement IDisposable), so developers are responsible for ensuring that this happens. Generally, a good place to do this is in the implementation of the Dispose() method of hubs:

public class CustomerHub : Hub
{
    ...
    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            _customerRepository.Dispose();
            _mailManager.Dispose();
        }
    }
}

It would be necessary to do this at least with direct dependencies of the hub that implement IDisposable. If these depend in turn on other components, the latter could be released here or from their respective Dispose() methods. In any case, it is also a task that must be performed with extreme caution, because there might be components shared between instances whose early release could cause problems.

With the techniques seen before, we now know how to inject dependencies in hubs by simply changing the content of the Dependency Resolver register, although this task can be really laborious if we have complex dependency graphs. For example, if our hub depends on an instance that implements the IService interface, the specific class to be used needs an instance of IRepository, and in turn this instance requires an IDataStore object. We can find ourselves with quite convoluted registers, because we have to manage these relationships ourselves:

GlobalHost.DependencyResolver.Register(
    typeof (MyHub),
    () => new MyHub(new MyService(new MyRepository(new MyDataStore())))
);

A concept that frequently appears hand-in-hand with Dependency Injection is that of Inversion of Control containers (IoC containers). These are components specializing in managing instances, life cycles, and dependencies between objects, something like Dependency Resolvers on steroids. Not only can they act as powerful Service Locators, but they also tend to be much more flexible when registering services, specifying instantiation modes (for example, deciding which objects will be created as singletons and which will be instantiated upon request), and solving dependencies between components automatically.

Going back to our previous example, where we had a dependency graph, if we were to request an instance of MyHub from the IoC container, the latter would be able to analyze its constructor and determine that it needs an instance of IService. Thanks to its register, it would know that IService must be resolved to the MyService class, but also that the latter, in turn, requires an IRepository object in its constructor, so it would check its register again to see what class would satisfy the dependency, and so on until completing the dependency graph.

Obviously, this way of managing dependencies is much more convenient and productive than doing it manually.

There are many IoC containers on the market, although we could point out Unity, Ninject, Autofac, StructureMap, or Windsor Castle, and others, for their great popularity. Virtually all are open source products, basically very similar in concept and operation, and even quite similar to the operation of the Dependency Resolver that we have previously seen:

IoC containers are normally integrated with SignalR through the standard mechanism of dependency resolution, because this is the point already established for obtaining component instances. Usually, the default Dependency Resolver is replaced with a custom one, which uses an IoC container in the backstage to obtain the dependencies making use of the latter’s power.

Now we will see how to use dependency injection with two of these containers: Unity and Ninject. The dependency graph that we will use is the following:

Broadcaster <requires> IMessageFormatter
MessageFormatter <implements> IMessageFormatter <requires> IClock

The Broadcaster hub requires in its constructor an instance of IMessageFormatter, which materializes in the MessageFormatter class and whose constructor, in turn, requires an instance of IClock. In all cases, the interfaces are a true reflection of the signature of the classes, so we will omit their code for the sake of brevity.

public class Broadcaster: Hub
{
    private IMessageFormatter _formatter;
    public Broadcaster(IMessageFormatter formatter)
    {
        _formatter = formatter;
    }
    public Task Broadcast(string message)
    {
        var formattedMsg = _formatter.Format(message);
        return Clients.All.Message(formattedMsg);
    }
}
public class MessageFormatter : IMessageFormatter
{
    private IClock _clock;
    public MessageFormatter(IClock clock)
    {
        _clock = clock;
    }
    public string Format(string message)
    {
        return _clock.GetCurrentDateTime() + " > " + message;
    }
}
public class Clock : IClock
{
    public string GetCurrentDateTime()
    {
        return DateTime.Now.ToString("F");
    }
}

PM> Install-package Unity

public class UnityDependencyResolver : DefaultDependencyResolver
{
    private UnityContainer _container;
    public UnityDependencyResolver(UnityContainer container)
    {
        _container = container;
    }
    public override object GetService(Type serviceType)
    {
        if (_container.IsRegistered(serviceType))
        {
            return _container.Resolve(serviceType);
        }
        return base.GetService(serviceType);
    }
    public override IEnumerable<object> GetServices(Type serviceType)
    {
        return _container.ResolveAll(serviceType)
            .Concat(base.GetServices(serviceType));
    }
}

public void Configuration(IAppBuilder app)
{
    var container = new UnityContainer();
    container.RegisterType<IClock, Clock>();
    container.RegisterType<IMessageFormatter, MessageFormatter>();
    container.RegisterType<Broadcaster>();
    app.MapSignalR(new HubConfiguration()
         {
              Resolver = new UnityDependencyResolver(container)
         });
}

container.RegisterType<IClock, Clock>(
              new ContainerControlledLifetimeManager()
);

PM> Install-package Ninject

public class NinjectDependencyResolver : DefaultDependencyResolver
{
    private IKernel _kernel;
    public NinjectDependencyResolver(IKernel kernel)
    {
        _kernel = kernel;
    }
    public override object GetService(Type serviceType)
    {
        return _kernel.TryGet(serviceType)
               ?? base.GetService(serviceType);
    }
    public override IEnumerable<object> GetServices(Type serviceType)
    {
        return _kernel.GetAll(serviceType)
            .Concat(base.GetServices(serviceType));
    }
}

public void Configuration(IAppBuilder app)
{
    var kernel = new StandardKernel();
    kernel.Bind<IClock>().To<Clock>().InSingletonScope();
    kernel.Bind<IMessageFormatter>().To<MessageFormatter>();
    app.MapSignalR(new HubConfiguration()
                {
                    Resolver = new NinjectDependencyResolver(kernel)
                });
}

Hubs are normal classes and, as such, they can be instantiated and fed with the dependencies they need, so we can decouple them from the remaining components of our application very easily and therefore subject them to unit tests without too much trouble with the techniques and tools that we have been looking at.

Furthermore, SignalR was designed from the outset with decoupling, dependency injection, and unit testing in mind, so it will facilitate performing unit testing of our applications. Virtually all communication that we can have between a hub and the components of the framework is done using abstractions (interfaces) that allow their replacement by mock objects that make unit testing easier.

For example, look at the following code of a hub, where we can see several interactions with the platform. The first one is to get the value of the header variable "Host", the second one is to get the connection identifier, and the third one is to send an information message to all connected clients:

public class Broadcaster: Hub
{
    ...
    public override Task OnConnected()
    {
        var host = Context.Headers["host"];
        var id = Context.ConnectionId;
        var message = "New connection " + id + " at " + host;
        return Clients.All.Message(message);
    }
}

Thanks to the abstractions used by the SignalR hub class and the magic of mocking frameworks such as Moq, we can create a complete dependency infrastructure whose behavior will be set up in advance so that we can focus on checking that in this method the Message method is invoked in all connected clients, sending them the exact message that we expect.

The verification code for the OnConnected() method of the hub would be as follows. Below we will go over it step by step:

[TestMethod]
public void On_Connected_sends_a_broadcast_with_a_specific_message()
{
    // 1) ARRANGE
    var hub = new Broadcaster();
    var connId = "1234";
    var host = "myhost";
    var expectedMessage = "New connection "+connId+" at "+host;
    // 1.a) Set up headers
    var mockRequest = new Mock<IRequest>();
    var mockHeaders = new Mock<INameValueCollection>();
    mockHeaders.Setup(h => h["host"]).Returns(host);
    mockRequest.Setup(r => r.Headers).Returns(mockHeaders.Object);
    // 1.b) Set up context & connection id
    hub.Context = new HubCallerContext(mockRequest.Object, connId);
    // 1.c) Set up capture of client method call
    var clientMethodInvoked = false;
    var messageSent = "";
    dynamic all = new ExpandoObject();
    all.Message = new Func<string, Task>((string message) =>
    {
        clientMethodInvoked = true;
        messageSent = message;
        return Task.FromResult(true);
    });
    var mockClients = new Mock<IHubCallerConnectionContext>();
    mockClients.Setup(c => c.All).Returns((ExpandoObject)all);
    hub.Clients = mockClients.Object;
    // 2) ACT
    hub.OnConnected().Wait();
    // 3) ASSERT
    Assert.IsTrue(clientMethodInvoked, "No client methods invoked.");
    Assert.AreEqual(expectedMessage, messageSent);
}

Note how, little by little, we are creating the scaffolding needed to execute the method to be tested, to ensure that it can retrieve the information from its environment, and to capture the calls to the client side:

Because preparing this entire infrastructure is sometimes rather tedious, it is often included in helper methods so that all tests can quickly obtain an instance of the hub to be checked, but already configured and ready for us to focus directly on implementing the various tests:

[TestClass]
public class BroadcasterTests
{
    // Helper method
    private Broadcaster GetConfiguredHub()
    {
        var hub = new Broadcaster();
        var connId = "1234";
        var host = "myhost";
        // Set up headers
        var mockRequest = new Mock<IRequest>();
        var mockHeaders = new Mock<INameValueCollection>();
        mockHeaders.Setup(h => h["host"]).Returns(host);
        mockRequest.Setup(r => r.Headers)
                   .Returns(mockHeaders.Object);
        // Set up user
        var identity = new GenericPrincipal(
              new GenericIdentity("jmaguilar"), new[] { "admin" });
        mockRequest.Setup(r => r.User).Returns(identity);
        // Set up context & connection id
        hub.Context = new HubCallerContext(mockRequest.Object,
                                           connId);
        return hub;
    }
    [TestMethod]
    public void Test1()
    {
        // Arrange
        var hub = GetConfiguredHub();
        ...// Test hub
    }
    [TestMethod]
    public void Test2()
    {
        // Arrange
        var hub = GetConfiguredHub();
        ... // Test hub
    }
}

Let’s look at one more example to show how to resolve other common scenarios when performing this type of testing. The hub method to be tested will be the following:

[Authorize]
public Task PrivateMessage(string destConnectionId, string text)
{
    var sender = Context.User.Identity.Name;
    var message = new Message() { Sender = sender, Text = text };
    return Clients.Client(destConnectionId).PrivateMessage(message);
}

In this case, we will first need to inject information about the active user into the instance of the hub. To do this, we preset the request context so that when its User property is accessed, a generic identity is returned. The code is similar to the example that we have recently seen:

var mockRequest = new Mock<IRequest>();
var identity = new GenericPrincipal(
        new GenericIdentity("jmaguilar"), new[] { "admin" });
mockRequest.Setup(r => r.User).Returns(identity);
...
// Set up context & connection id
hub.Context = new HubCallerContext(mockRequest.Object, connId);
...

We must also capture the call to the PrivateMessage method of the dynamic object returned by the call to Clients.Client(connectionId), which can be achieved in very much the same way as we did earlier:

[TestMethod]
public void PrivateMessage_Sends_A_Private_Mesage()
{
    // Arrange
    var hub = GetConfiguredHub();
    var destinationId = "666";
    var user = hub.Context.User.Identity.Name;
    var text = "Hi there!";
    var mockClients = new Mock<IHubCallerConnectionContext>();
    Message messageSent = null;
    dynamic client = new ExpandoObject();
    client.PrivateMessage = new Func<Message, Task>((Message data) =>
                                {
                                   messageSent = data;
                                   return Task.FromResult(true);
                                });
    mockClients.Setup(c => c.Client(destinationId))
               .Returns((ExpandoObject)client);
    hub.Clients = mockClients.Object;
    // Act
    hub.PrivateMessage(destinationId, text).Wait();
    // Assert
    Assert.IsNotNull(messageSent, "Message not sent");
    Assert.AreEqual(user, messageSent.Sender);
    Assert.AreEqual(text, messageSent.Text);
}

Another possibility that we have for capturing calls to client-side methods is to use a mock interface with the operations that are allowed and to configure a callback function on the call, to retrieve the information sent. The main section of the setup code would be as follows:

...
var mockClients = new Mock<IHubCallerConnectionContext>();
var mockClientOperations = new Mock<IClientOperations>();
mockClientOperations
    .Setup(c => c.PrivateMessage(It.IsAny<Message>()))
    .Returns(Task.FromResult(true))
    .Callback<Message>(msg =>
                        {
                            messageSent = msg;
                        });
mockClients.Setup(c => c.Client(destinationId))
           .Returns(mockClientOperations.Object);
hub.Clients = mockClients.Object;
...

The definition of the interface, used only to configure the behavior of the PrivateMessage() method with Moq, would be as follows:

public interface IClientOperations
{
    Task PrivateMessage(Message msg);
}

We have seen that performing unit tests on hubs need not be especially complicated if we master a mocking framework, which, incidentally, is absolutely recommended. If the class has been built without rigid dependencies, we will always find a way to perform isolated tests on the aspects that we want. The SignalR architecture itself also makes it very easy for us, because we work on abstractions of components that can be easily replaced with other ones.

With persistent connections, things change a bit, because SignalR does not offer so much flexibility anymore. From its base, testing this type of component is a little more difficult because the custom code is implemented on protected methods inherited from their parent class, PersistentConnection. Thus, any attempt to invoke one of the overridable methods such as OnReceived or OnConnected from the outside—for example, from a unit test—will generate a compilation error because they are not visible from outside the base class or its descendants:

// Arrange
var connection = new MyConnection();
...
// Act
connection.OnReceived(mockRequest.Object, connId, data); // Error
...

The solution to this problem is really simple: we just need to create in the test project a new class inherited from the connection that we want to test and create public methods in it that function as “bridges” to the methods of the base class. We would do the tests on these new methods because they would be visible from the test classes:

public class MyTestableConnection : MyConnection
{
    public new Task OnReceived(IRequest request,
                                string connectionId, string data)
    {
        return base.OnReceived(request, connectionId, data);
    }
}

Note that, in the constructor of this new class, we would also have to include the dependencies that the original persistent connection requires, if any.

However, when this obstacle is overcome, as soon as we begin testing the code, we will see that there are members that we would like to replace so as to take control in tests, but there is no way to do it. Perhaps the most evident case is found in the Connection property that we use from persistent connections to make direct submissions or broadcasts to clients; its setter is private, and it is set internally in the class. The process is unable to be intercepted or altered from any point.

Therefore, the recommendation regarding unit testing on this type of component is to remove as much code as possible from the methods to be tested (OnConnected, OnReceived, and so on), especially code related to Connection or other non-replaceable components, taking them to points where we can control them, using dependencies, inheritance or any other mechanism that can provide alternative implementations.

To illustrate these problems and how to solve them, we are going to implement some tests on the following persistent connection. Note that we have omitted all references to the Connection property of PersistentConnection, and to make submissions, we are using a custom abstraction, which we have named IConnectionWrapper, whose code we will look at later on:

public class EchoConnection : PersistentConnection
{
    private IConnectionWrapper _connection;
    public EchoConnection()
    {
        _connection = new ConnectionWrapper(this);
    }
    public EchoConnection(IConnectionWrapper connection)
    {
        _connection = connection;
    }
    protected override Task OnConnected(IRequest request,
                                        string connectionId)
    {
        var newConnMsg = "New connection " + connectionId + "!";
        return _connection.Send(connectionId, "Howdy!")
                            .ContinueWith(_ =>
                                _connection.Broadcast(newConnMsg)
                            );
    }
}

That is, we are replacing the references to this.Connection, rigid and difficult to control from unit tests, with others with no coupling whatsoever. We also define two constructors: the first one will be the one normally used at run time, whereas the second one is prepared to be able to inject the dependencies from the tests.

The abstractions that we have used are the following:

public interface IConnectionWrapper
{
    Task Send(string connectionId, object value);
    Task Broadcast(object value, params string[] exclude);
}
public class ConnectionWrapper: IConnectionWrapper
{
    private PersistentConnection _connection;
    public ConnectionWrapper(PersistentConnection connection)
    {
        _connection = connection;
    }
    public Task Send(string connectionId, object value)
    {
        return _connection.Connection.Send(connectionId, value);
    }
    public Task Broadcast(object value, params string[] exclude)
    {
        return _connection.Connection.Broadcast(value, exclude);
    }
}

From the testing project, we cannot use the EchoConnection class directly because its members have protected visibility, so we must now create the wrapper that will serve as a gateway to said class:

public class TestableEchoConnection : EchoConnection
{
    public TestableEchoConnection(IConnectionWrapper connWrapper)
        : base(connWrapper) { }
    public new Task OnReceived(IRequest req, string id, string data)
    {
        return base.OnReceived(req, id, data);
    }
    public new Task OnConnected(IRequest req, string id)
    {
        return base.OnConnected(req, id);
    }
}

Now we can finally implement our unit test, where we verify that when the OnConnected method of the persistent connection is invoked, a submission using Send() and another one using Broadcast() are made:

[TestMethod]
public void On_Connected_Sends_Private_And_Broadcast_Messages()
{
    // Arrange
    var mockConnection = new Mock<IConnectionWrapper>();
    mockConnection
        .Setup(c => c.Send(It.IsAny<string>(), It.IsAny<object>()))
        .Returns(Task.FromResult(true))
        .Verifiable();
    mockConnection
        .Setup(c => c.Broadcast(It.IsAny<object>()))
        .Returns(Task.FromResult(true))
        .Verifiable();
    var echo = new TestableEchoConnection(mockConnection.Object);
    var myConnId = "1234";
    var mockRequest = new Mock<IRequest>();
    //Act
    echo.OnConnected(mockRequest.Object, myConnId).Wait();
    // Assert
    mockConnection.Verify(); // Verify expectations
}

When we studied the possibilities that existed for communicating other threads with the clients connected to a SignalR service, we anticipated the possibility of having a service façade to act as a gateway between external systems and hubs or persistent connections of our application, as shown in Figure 9-6.

Figure 9-6. Access to real-time services from external systems.

This possibility can come in handy when we have external systems from which we need to send messages to a SignalR application for the latter to process them and, where applicable, inform the connected users in real time. For example, we could have a SignalR-based instant messaging service for corporate users, and we could have other applications of the company, such as its ERP or CRM system, send notifications of interest through said service in real time.

Such external systems, which could be created in any language or technology, would send their notifications to the messaging service by using an RPC mechanism toward a façade located on the SignalR application. From this façade, the messages could be sent to the users concerned, using the techniques already seen to access hubs or persistent connections from other threads.

There are several technologies with which we could write a similar facade, from traditional SOAP/XML-based Web Services to the latest Web API framework. Due to the latter’s popularity and growing usage trend, we will dedicate this section to it.

From Web API actions, it is very easy to access the clients connected to a SignalR service. We have already seen how to achieve it by using the ConnectionManager property of the GlobalHost object, through which we can obtain the context of a hub or persistent connection and send messages to its connected clients or manage its groups:

var ctx = GlobalHost.ConnectionManager.GetHubContext<Chat>();
ctx.Clients.All.SendMessage("The system is shutting down now!");

This possibility alone would allow us to obtain a reasonable integration of SignalR in our Web API–based services, but we still have other options to achieve it in a more efficient and productive way. For example, it would be quite easy to create a base controller for Web API specifically designed to facilitate access to hubs. Such a controller could be like the following:

using System.Web.Http;
using Microsoft.AspNet.SignalR;
using Microsoft.AspNet.SignalR.Hubs;
public abstract class ApiHubController<T> : ApiController
    where T : Hub
{
    protected IHubConnectionContext Clients { get; private set; }
    protected IGroupManager Groups { get; private set; }
    protected ApiHubController()
    {
        var ctx = GlobalHost.ConnectionManager.GetHubContext<T>();
        Clients = ctx.Clients;
        Groups = ctx.Groups;
    }
}

As you can see in the preceding code, we are defining the ApiHubController class with a generic type parameter T, where T is a Hub of SignalR. As it inherits from ApiController, we can safely use this class as a base for our Web API controllers, as follows:

public class MyChatController: ApiHubController<Chat>
{
    // Actions
}

The implementation of our Web API controllers will be the same as always. The only difference is that, when accessing the hub, the base class offers shortcuts to its features via controller properties instead of doing so via GlobalHost.ConnectionManager. These properties are as follows:

In the source code repository of the Web API framework on CodePlex, we can find a project called System.Web.Http.SignalR^[43] with an implementation of base controllers that is conceptually similar to the one we have seen in this section, only broader.

Obviously, we could use the same technique to create Web API controllers oriented to facilitating the use of persistent connections instead of hubs. It could be very similar to the one previously shown:

using System.Web.Http;
using Microsoft.AspNet.SignalR;
public abstract class ApiConnectionController<T> : ApiController
       where T : PersistentConnection
{
    protected IConnectionGroupManager Groups { get; private set; }
    protected IConnection Connection { get; private set; }
    protected ApiConnectionController()
    {
        var ctx = GlobalHost.ConnectionManager.GetConnectionContext<T>();
        Connection = ctx.Connection;
        Groups = ctx.Groups;
    }
}

ASP.NET MVC, the popular framework for creating web applications, does not have any component or adapter for integration with SignalR to facilitate the use of hubs or persistent connections.

Thus, basic integration with MVC controllers should be achieved by obtaining the context of the persistent connection or hub at the point from which we want to invoke their functions:

public class HomeController: Controller
{
    public async Task<ActionResult> ShutDown()
    {
        var ctx = GlobalHost.ConnectionManager.GetHubContext<Chat>();
        await ctx.Clients.All.SendMessage("System shutting down!");
        return RedirectToAction("ClientsNotified");
    }
}

However, we could also easily achieve a similar result to the one previously obtained with Web API if we use the same idea to create controller classes specific for using hubs or persistent connections from the MVC framework. The following could be an example:

using System.Web.Mvc;
using Microsoft.AspNet.SignalR;
using Microsoft.AspNet.SignalR.Hubs;
public abstract class HubController<T> : Controller
    where T : Hub
{
    protected IHubConnectionContext Clients { get; private set; }
    protected IGroupManager Groups { get; private set; }
    protected HubController()
    {
        var ctx = GlobalHost.ConnectionManager.GetHubContext<T>();
        Clients = ctx.Clients;
        Groups = ctx.Groups;
    }
}

Notice that the only difference with the Web API controller is that, in this case, we inherit from System.Web.Mvc.Controller. Thus, we could easily use it as a base for our MVC controllers:

public class ChatController : HubController<EchoHub>
{
    ...
    [HttpPost]
    public async Task<ActionResult> Broadcast(string message)
    {
        await Clients.All.Message(message);
        return Json(new {success = true});
    }
}

Now, on the client side, we are going to see how we could integrate a SignalR client with Knockout^[44], the open source framework based on the popular presentation layer design pattern MVVM^[45].

In this framework, there is a complete separation between the presentation elements, the logic that is responsible for managing presentation, and the data it uses. Thus, we will define the interface on the one hand (basically an HTML template with some special features) and the View-Model object on the other hand (which contains the data that feed said template and the logic to manage interactions).

For example, the following code could correspond to the markup of a page that uses Knockout to show a small text submission form and a list of messages received just below. Note that there is no reference to SignalR, only the Knockout binding system’s own attributes that indicate different aspects of the behavior and display of the elements of the interface:

...
<h1>Knockout Broadcaster</h1>
<div>
    <input type="text" data-bind="value: text, enable: ready" />
    <button data-bind="click: send, enable: ready">Send</button>
</div>
<p data-bind="visible: !ready()">Connecting...</p>
<ul data-bind="foreach: messages, visible: ready">
    <li data-bind="text: $data"></li>
</ul>
...

At run time, when connected to SignalR (we will see how to do this later on), the result displayed on screen would look like what you see in Figure 9-7.

Figure 9-7. Knockout and SignalR executing.

In the preceding HTML code, we see the attributes that indicate binding rules of each element of interest with members of the View-Model object, which in Knockout are always called data-bind. One step at a time:

The binding system uses observables in both directions. Thanks to the Knockout dependency management system, if any property of the View-Model changes, the interface will be automatically updated according to the binding rules set, and the same applies in the opposite direction: any update to the data entry fields will be immediately reflected in the properties of the View-Model.

The following code could be the View-Model class for the preceding example. It could be found in a separate script file referenced from the page or on the page itself:

var BroadcasterViewModel = function (hub) {
    var self = this;
    self.ready = ko.observable(false);
    self.text = ko.observable("");
    self.send = function () {
        if (self.ready()) {
            hub.server.broadcast(self.text()).done(function() {
                self.text("");
            });
        }
    };
    self.messages = ko.observableArray();
    self.start = function() {
        $.connection.hub.start().done(function() {
            self.ready(true);
        });
    };
    hub.client.message = function(msg) {
        self.messages.push(msg);
    };
};

The class constructor takes as an argument a reference to the hub on which it will act, and as we can see, the members who were referenced from the bindings are defined on the object itself. The properties are set and queried using ko.observable()^[46] objects, which are the ones that provide automatic dependency management. For example, the ready property is initially set to false, and it is set to true only when the connection to the hub is completed, whereupon all controls depending on it will automatically update their states, enabling and showing themselves.

The methods are declared directly on the class, and they can use the internal properties to perform their tasks.

The code that would initialize the page would be the one shown in the following example. All that we would need to do in this case is to instantiate the View-Model and supply it the hub on which it will operate, tell Knockout that it must use this instance as a reference for the bindings, and finally, invoke the method that we have prepared in the View-Model to start the connection to the Hub:

$(function () {
   var vm = new BroadcasterViewModel($.connection.broadcaster);
   ko.applyBindings(vm);
   vm.start(); // Starts the connection
});

Finally, the hub on which we have been working is shown here:

public class Broadcaster: Hub
{
    public override Task OnConnected()
    {
        return Clients.All
                 .Message("New connection " + Context.ConnectionId);
    }
    public Task Broadcast(string message)
    {
        return Clients.All
                 .Message(Context.ConnectionId +"> " + message);
    }
}

Of course, we can also easily integrate a SignalR client into applications built with AngularJS^[47], the popular SPA^[48] framework based on the MVC pattern.

In AngularJS, views are also defined independently of the other components, and as we saw with Knockout, attributes (directives, in Angular slang) are used to specify the behavior of DOM elements. The following HTML code shows the view portion of an application similar to the one we saw in the preceding section:

<body ng-app="angularDemo" ng-controller="BroadcasterController"
                           ng-init="start()">
    <h1>AngularJS Broadcaster</h1>
    <div>
        <input type="text" ng-model="text" ng-disabled="!ready" />
        <button ng-click="send()" ng-disabled="!ready">Send</button>
    </div>
    <p ng-hide="ready">Connecting...</p>
    <ul ng-show="ready">
        <li ng-repeat="msg in messages">{{msg}}</li>
    </ul>
</body>

In the <body> tag, we are specifying the name of the application (“angularDemo”), the name of the controller class (BroadcasterController), and the latter’s method to be executed when the application starts. We will use this moment to start the connection to SignalR, as we will see later on.

Next we encounter the following:

Note that, despite the differences in syntax, the concepts are very similar to those seen with Knockout. To get a graphical idea, the running result of the AngularJS application that we are building would be what’s shown in Figure 9-8.

Figure 9-8. SignalR clients written with AngularJS and Knockout.

We will now look at the code of the controller class. This class is created automatically by AngularJS—its name is stated in the markup code—and in its constructor, it receives an argument called $scope that references the instance of the model class that is used and on which we must define the properties and methods that we need to use from our application. We have previously referenced the following properties and methods: ready, text, messages, send(), and start():

function BroadcasterController($scope, hub) {
    $scope.ready = false;
    $scope.text = "";
    $scope.messages = [];
    $scope.send = function () {
        if ($scope.ready) {
            hub.broadcast($scope.text);
            $scope.text = "";
        }
    };
    $scope.start = function () {
        hub.start(function () {
            $scope.$apply(function () {
                $scope.ready = true;
            });
        });
    };
    hub.messageReceived(function (msg) {
        $scope.$apply(function () {
            $scope.messages.push(msg);
        });
    });
}

An important aspect to keep in mind when programming on AngularJS is that changes in the properties of the controller that do not come directly from events or actions managed by this framework will not be detected automatically, so the user interface will not be updated at times. In our example, this happens when we receive data from the SignalR server (implemented in the callback defined in hub.messageReceived) or when we are notified that the connection was successful. In both cases, we must use $scope.$apply() to inform Angular that changes occurred and to force its evaluation to refresh the user interface when necessary.

However, AngularJS is equipped with a magnificent out-of-the-box dependency injection system that makes it quite easy to implement controllers decoupled from the other components, allowing us to create better structured applications that are simpler and easier to maintain, as well as allowing us to perform unit tests on these classes.

In fact, you can see in the preceding code that there are no direct references to $.connection nor to any of its elements, because a service class is received as a dependency and it implements the functionalities that we need from the hub. Thus, from a unit test, we could instantiate the controller class and supply it mock objects, useful to check in an isolated manner that the operation of this component is correct.

The service class is defined as follows on the main module of the application. The name “hub” with which we created the class is used by Angular to perform automatic dependency injection; when it finds a parameter in the controller class with that name, it will search to see whether there is a factory for it in the module and use the value returned by it:

angular.module('angularDemo', [])
    .factory('hub', function () {
        return {
            start: function (successCallback) {
                $.connection.hub.start().done(successCallback);
            },
            broadcast: function (msg) {
                $.connection.broadcaster.server.broadcast(msg);
            },
            messageReceived: function (callback) {
                $.connection.broadcaster.client.message = callback;
            }
        };
    });

In this class are the three features that we need from the SignalR client for this application and that are used from the controller class: start(), to start the connection; broadcast(), to send a message to the server; and messageReceived(), which allows defining the callback to receive messages.