In this recipe, we'll describe the first operation that is necessary in every client-side portion of a SignalR application: connecting to a server. We'll quickly see how to do it and how the asynchronous nature of SignalR is already clear since the very first step performed by any client.
This recipe is only about performing a connection; that's why we do not need a server-side concrete Hub yet. Therefore, there is only one simple step that we need to perform before moving to the client-side code as follows:
- We need to add an OWIN Startup class and set it up so that the
Configuration()method callsapp.MapSignalR();in order to properly initiate the server-side endpoint, as we already did several times in the previous chapters. This method is contained in the Microsoft ASP.NET SignalR System.Web package, which we can find on NuGet. If we use the graphical UI, we should search for it and install it from there. This is depicted in the following screenshot:
The same result can be achieved using the command line supplied by the Package Manager Console package.
- When you are done, let's add an HTML page called
index.html, where we'll build our client. We need to reference the SignalR JavaScript client, which is normally added to the project when referencing the Hub type, but in this case, we do not add any Hub-derived class. So, we have to add the Microsoft ASP.NET SignalR JavaScript Client NuGet package manually, as shown in the following screenshot:
Now that everything is in place, let's add the necessary bits into the <head> section of our page. We need to perform the following steps:
- Add a reference to jQuery (remember, the SignalR JavaScript library is a jQuery plugin, so this is a requirement) using the following code:
<script src="Scripts/jquery-2.1.0.js"></script>
- Add a reference to the SignalR JavaScript library using the following code:
<script src="Scripts/jquery.signalR-2.0.2.js"></script>>
- Add a reference to the SignalR dynamic endpoint:
<script src="/signalr/hubs"></script>
- Add the following simple script that will help you to connect to the server:
<script> $(function () { var hub = $.connection.hub; var started = hub.start(); started.done(function() { $('#connected').html('connected!'), }); }); </script>
That's it; very simple. We first take a reference to the $.connection.hub object, which is an entry point to access the details of a connection specific to the Hubs API, and then we start the server. The start() method returns a JavaScript promise object and then starts connecting asynchronously. Thanks to the promise object, we can hook a callback that will be invoked when the connection is ready by using the done() method. Inside the callback, we refer to an HTML paragraph called connected (which must exist on the page) and set its content to the 'connected' value. We can easily verify this behavior by running the project and visiting the index.html page.
The SignalR dynamic endpoint returns a script that, when downloaded, executes and adds the hub member to the $.connection object through which we can then asynchronously initiate a connection. There are several ways to perform this task as we'll see later in this chapter. Behind the scenes, the client and the server negotiate the better transport strategy to use. This phase occurs on the network, and as already mentioned in the past, anything requiring remote communication happens asynchronously. That's why a promise object is used to expose this specific phase in a neat and idiomatic way.
If you want to learn more about JavaScript promises in general and in particular about the Deferred API, which is exposed by jQuery and used by SignalR, you could start by visiting http://api.jquery.com/category/deferred-object/. If you want to know more about the connection strategies that we just mentioned, you can instead go straight ahead to the following recipe.