Chris Risner . Com

Getting SignalR to Work with Azure and Orleans

Posted on: 10/23/2014 9:18:00 PM by

SignalRI 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:


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!

Categories: Azure, Games, Web
Bookmark and Share
First Article

Building a Text Adventure with Azure and Orleans

Posted on: 10/22/2014 9:13:00 PM by

Colossal AdventureBack in May of this year, we did an episode on Cloud Cover focusing on project Orleans.  Orleans is a project created by Microsoft Research that provides an easy way to build distributed high-scale computing applications.  You can build these without having to spend months learning and understanding complex concurrency and scaling patterns which is always nice.  If you’ve done .NET development and are familiar with the awesomeness of async / await, picking up project Orleans is very easy to do.  Orleans does this using the actor model which I’ll talk more about in a minute.  One of the other great things about Orleans is that it’s built from the ground-up with the cloud in mind.  So getting it on to Azure is pretty easy to do. 

TLDR: You can play the game here:

TLDR: You can check out the source code here.

One of the samples in the Orleans release is a simple text adventure game named, Adventure.  This game is in the same style as Zork or Colossal Adventure which many people are familiar with (if you aren’t, you can actually play Colossal Adventure on AMC’s Halt and Catch Fire website!).  The general idea is that everything is text based.  Players read about their surroundings and then type in what they want to do.  These text adventures, called Interactive Fiction, were some of the first computer games.  I’ve been meaning to get back to doing some more game dev so a little over a month ago, I started on a small side project to make a text adventure game on top of Azure using the Orleans Framework.  I started by combining the Adventure sample with the Azure sample for Orleans and got the basic Adventure game running on Azure.  Before I go over the details of that, I should explain how Orleans works.

The actor model and Orleans

The actor model is a model for concurrent-computation set forth by Carl Hewitt in 1973.  Under the actor model, the actor is the sole primitive.  It handles both behavior and state.  Actors interact with other actors and communicate via asynchronous messages delivered via system-generated proxies.  Actors don’t contain other actors but may have a reference to them (though that reference is just used to send messages as opposed to having direct access).  In Orleans, the actors are called Grains.  So every actor in the system is it’s own Grain.  In order to contain the grains, Orleans has Silos.  As the developer, you don’t develop the silo as much as start a silo.  The Orleans framework then knows how to make use of the silos to contain the grains.  In addition, the “location” where the grains perform all of their actions is within the silo.  When you need access to a grain, you don’t create a new instance using “new” but instead rely on a generated GrainFactory to get an activation for a grain.  In this way, grains are never created nor destroyed.  They are activated or deactivated as needed by the system.  Additionally, grains handle their own state storage (with some work on your part in the Grain code) so persistence is transparent to the client making calls into the Grain.  This all may sound a bit confusing but I’ll follow up this post with another explaining more about the architecture of Orleans and the sample I built so it will make more sense.

Azure and Orleans

When it comes to Orleans, Azure is a natural fit for deployment.  Orleans includes a number of step-by-step tutorials which explain how to get started with Orleans.  One of the most useful is one that explains cloud deployment.  To deploy to Azure, you essentially map your application onto Worker and Web Roles inside of Azure Cloud Services.  The Worker Role(s) run the Orleans Silos where all of your Grains’ functionality takes place.  The Web Role(s) run the client code for your application whether it’s a web site or a web service.  So the web code get’s access to your Grains and request them to perform whatever actions they need.  Orleans is built around C# asynchronous programming so everything uses Async and Await.  So every call you make against a grain is asynchronous and you await it from the client until you get the result.  The great thing about this is that due to the Orleans framework, you get high-scalability and concurrency out of this approach without really needing to know more more than what I just described (there is more to know but I’ll get to that in future posts).  You can optionally tie a GrainState to each Grain.  When you do this, you can specify a Store where your grains’ state should be persisted.  Orleans includes some built in storage providers that make storage super simple by just applying an annotation ([StorageProvider(ProviderName=”name”)]) on your Grain classes.  For example, you can very easily start storing your grains’ state into Azure Table Storage by setting up your store, putting the connection string in your config files, and annotating the classes.  Rather than assume when you want to persist data, Orleans leaves it to you to call State.WriteStateAsync(); in your Grain’s code whenever you want to store the state.  Restoring the state is done automatically whenever you activate a grain that has been idle for too long.  There have been a number of community contributions for storage providers but you can also easily write your own storage provider as well.  You can check out a ton of community contributions for Orleans here.

Adventure Terre

The basic game sample doesn’t have a TON of functionality.  Out of the box it includes the following:

  • View a description of a room
  • Move from room to room
  • Pick up and drop things
  • Kill monsters if you have the right item

This is enough to show the concept but isn’t really enough to make a game.  To make the game a bit more full fledged I added the following to the public source release:

  • Store a game state (essentially a collection of string-booleans to track individual flags)
  • Descriptions of rooms, monsters, and NPCs that are shown based off of flags
  • Ability to set flags when a descriptor is shown
  • Ability to make NPCs and Monsters move throughout the world in random directions (using Orleans timers)
  • Ability to send messages down to Players using SignalR (this was really cool to get going so I’ll talk about this in a future post)
  • Ability to speak to NPCs and Monsters
  • Non-Playable Characters (essentially monsters that can’t be killed)
  • Ability to specify where monsters and NPCs should start in the world
  • Ability to change directions a player can move in based off of the game state flags
  • Ability to specify different descriptions for items based off of flags
  • Ability to specify flags that should change when items are used (and how they can be used)
  • Ability to specify State Change Actions (things that should occur when flags are changed)

So I added a ton of features.  I actually added a few more features to the non-public release but very little functionality on top of the above.  The majority of the time was spent working on the above as opposed to the story (that will be apparent if you give it a try). 

AdventureTerre Architecture

I’ll give a little detail today on what the architecture of the game looks like to hopefully provide more detail on how something is built with Orleans.  As mentioned above, everything is a Grain.  So in this game the following Grains exist:

  • Players
  • Rooms
  • Monsters
  • NPCs
  • GameState
  • PushNotifiers (I’ll cover this in the future when I talk about SignalR)

For every player a PlayerGrain is generated and it keeps track of the rooms, monsters, NPCs, and game state.  When a request comes in, the PlayerGrain figures out what needs to be done and calls out to the other grains.  All of these Grains have interfaces which implement some form of IGrain and specify an interface that extends IGrainState.  All of the grains also specify that they use the AzureStore so that whenever their data needs to be written or read, Azure Table Storage is used. 

That all happens within the Worker Roles.  However, players don’t have any direct interaction with those roles.  Instead, when you want to play the game, you go to a website running in the Web Roles.  The interface the player plays in resembles a terminal window (yay nostalgia) which runs locally with JavaScript.  Every command is passed to a web service exposed as part of the web site.  That web service handles getting the PlayerGrain and calling whatever actions on the grain are necessary.

Design Considerations

While I’m happy to consider myself done with this sample for now, there are a number of things I did that if I had thought things out better at the beginning or had more time now, I’d change.  First, the original sample treated Things (items like weapons and food) not as Grains, but objects either in a RoomGrain or on a PlayerGrain.  One feature I added to the final game was the ability to hide and unhide items.  Leaving items as objects in the State of Players and Rooms made this more difficult than if they had been Grains as well.  Another change I’d make was how I treated the GameStateGrain.  Originally there was just a dictionary on the PlayerGrain that contained the state.  While trying to diagnose an issue with await / async (more on this in the future) I moved the dictionary into it’s own Grain.  This worked, and still works, but did make a few things more complicated.  There were a few other pain points I’d change but for now, it works and it’s being shipped.

The Game

The game itself ended up being quite small (definitely smaller than Zork for example) but showed several different capabilities and it works.  If you play it, you’ll easily get though doing absolutely everything there is in less than 20 minutes.  I’m hoping this will spur me to get back into actual game development.  For now, you can pull down the source code and deploy it yourself to Azure by going here.  Finally, I encourage everyone to go play the game for a few minutes and remember that everything is running in a super scalable backend powered by Azure. 

Categories: .Net, Azure, Javascript, Web
Bookmark and Share
First Article