I just recently posted the source code and link to the Adventure style game I built with Orleans and Azure. Today I’d like to talk briefly about how I got SignalR to work. If you haven’t looked at SignalR before, it’s a very cool library which makes it easy to add real-time functionality to your applications. In more simple terms, it makes it possible for you to push information from your server to the client instead of having to ask for updates. This is really powerful because you can deliver instant updates to the client when a change happens on the server.
To add SignalR to my sample, I worked off of the GPSTracker sample provided with Orleans. One issue I had to figure out that the GPS Tracker doesn’t cover is getting things to work on Azure. As it turns out (and I’ll provide more detail below) there weren’t any big changes just because we were on Azure, however, figuring out how to open the path from Worker Roles to Web Roles for SignalR was something I had deal with.
SignalR in AdventureTerre
For AdventureTerre, there were a few different scenarios I thought SignalR might be useful. If you go play the game right now, I didn’t leave any of them in but turning them on is easy. The first scenario and the one I implemented was having monsters (as well as NPCs) have the ability to move between rooms. The way this works is that, if specified that they should be able to move, an Orleans timer is created on the grain telling it to attempt to move very couple of minutes. The timer causes a method on the Monster / NPC grain to fire which will randomly choose a direction and then, if there is a room in that direction, will move the monster / NPC. When this happens a message is sent to any players in the old room letting them know the character left the room and a different message is sent to any players in the new room letting them know the character has entered the room. Pretty simple but a much better experience than looking at a room one second and not seeing a monster there and looking again a second later and seeing one there. There were other possible scenarios I thought of including having the monsters / NPCs randomly say something to players in the room as well as having players say things to one another (right now the game is strictly single player).
SignalR and the Web Layer (Web Roles)
Getting SignalR to work with Orleans requires a little more thought due to how SignalR and Grains work. When a client (our website) opens, we use JavaScript to connect to a Hub running in our web application. Upon connecting to the Hub, the hub adds the client’s connection to a group based off of a cookie value (which is also tied to the player). These groups are how messages are later sent. Essentially the hub is told “send this data to this recipient” and the hub does that based off the group they’re in. (since the cookie is tied to the player, when we want to deliver a message to the player, we tell the hub to deliver to the group also tied to the cookie value) let’s take a look at some of the code for this. First the JavaScript in our website:
This is pretty straight forward. We create a hub tied to a PlayerHub and start it which connects it to the Hub on the server. We also define the methods playerUpdate and playerUpdates. Now let’s look at the PlayerHub which is a Controller in the web app:
Here again we see the update methods though we specify who the message should be sent to (the Recipient field is the cookie value mentioned above). The OnConnected method makes sure it’s not a Grain connecting to the hub, and if it isn’t, adds the connection to a Group based off the cookie value. From the web app side, that’s all we need to do (you also need to reference the SignalR JS libraries and the SignalR NuGet where appropriate but I’ll leave that up to you).
SignalR and the Orleans Silo Layer (Worker Roles)
If we were just triggering pushes to our client when something happened in our Web Roles, we wouldn’t need to worry about anything else. However, our Grains and Silos are running in Worker Roles. Those Worker Roles don’t have any concept of our hubs or the connections they have to our clients. In order to deal with this, we add a PushNotifierGrain which handles talking from our Silos back to our Web Roles. Let’s first look at the interface, IPushNotifierGrain:
The important method here is the on that sends a message to a recipient. Let’s look at the implementation:
There’s a lot going on here but it’s all pretty easy to understand. The private vars hubs and messageQueue keep track of our hub references and a queue of messages to deliver respectively. ActivateAsync creates a timer to regularly flush (send out) messages, refresh our hubs, and creates a timer to refresh the hubs every once in a while. RefreshHubs goes through every instance and gets an endpoint based off of the InternalSignalR key. Once it does that it goes through and removes all old hubs and adds new ones. The rest of the methods should be pretty easy to understand.
Sending a message
When we want to deliver a message to a specific player it’s very easy to do so:
In this case, we’re first getting access to the only PushNotifierGrain ever used (we’re always using the one with the ID of zero). We’re then pulling out all of the players in the current room and getting their primary key (a GUID created with the above mentioned cookie). We can then call the SendMessage method on our PushNotifierGrain and pass in the message we want to deliver and the Guid we want to deliver it to. Once we call that, the PushNotifierGrain loops through all of the Hubs that it can connect to and sends the message to that hub. This means we’re sending our message to every hub (so each Web Role). It’s then up to the hubs (web role) to deliver the message if a client has registered with the hub with the cookie. So in the end only one hub will actually deliver the message down to the single client that should receive it!
The hard part: Exposing the endpoint
As I mentioned up near the top, it was pretty easy to take most of that from the GPS Tracker sample and adapt it to AdentureTerre. However, pushing it to Azure lead to an issue: there was no connection open for the Worker Roles to talk to the Web Roles. I spent way too much time trying to figure this out. The key to figuring out the problem was the name of the endpoint we’re looking for in the RefreshHubs method: InternalSignalR. This didn’t exist anywhere. As it turned out, this needs to be specified in the Azure deployment project’s ServiceDefinition.csdef file. You just need to add a new internal endpoint to the Site Bindings and the Endpoints:
Summary
And that’s pretty much it. Now not only can we “talk back” to our clients from the web but we can trigger updates from our Grains as well. Our application can be really interactive now. To see the SignalR stuff in action, all you need to do is change the movesRandomly flag of any of the characters to true. Then if you’re in the same room when a character tries to enter or leave that room, you’ll get a message pushed to you!
