Event Sourced Orleans Grain

Event Sourced GrainI always thought a Event Sourced Orleans Grain would fit a really well as a stateful Aggregate Root.  Take it a step further and have your Grain be event sourced and also encapsulate a projection of current state.  This post is going to setup the basics of how to Raise events and apply them in our Grain state.  I will be covering persisting the events in the next post.

Blog Post Series:

Event Sourced Grain

I’m going to create a typical example using a bank account.  There are basically two events we will raise.  Deposited event to indicated that we have deposited money into the account and and Withdrawn event to that we have taken money out of the account.

Orleans provides a package Microsoft.Orleans.EventSourcing  to help raise events from you Grain as well as apply them to the state.  From the package, you now can have your grain derive from JournaledGrain<TState, TEvent>.

Grain State

From the example Grain above we are missing our actual grain state, which really a projection so we can keep our current balance.  Once an event is Raised the Grain will call the appropriate Apply(T evnt) method in our state.


Next I’ll be persisting our events to Event Store.  This will include once a grain is activated, to pull the events and replay them to get to current state.


If you want to try the demo, all the source is available on my PracticalOrleans GitHub Repo.

Do you have any questions or comments? Are you using Orleans?  I’d love to hear about it in the comments or on Twitter.

Enjoy this post? Subscribe!

Subscribe to our weekly Newsletter and stay tuned.

Orleans Smart Cache Pattern

Orleans Smart Cache PatternI discovered the Orleans Smart Cache Pattern by listening to a talk by John Azariah and Sergey Bykov.  The idea is that you can use Orleans as a distributed cache in front of (permanent) storage.  This is really ideal if you have a read heavy system, which most are.  You could optionally also choose to buffer your writes when you make state changes.  Ultimately you will reduce load on your storage by accessing data/state from memory.

Blog Post Series:

Video Tutorial


State Holder Grain

The idea is we are going to create a Grain that will be used for holding/containing our state.  There are just two methods, setting and getting our state as defined in IStateHolderGrain<T>


For this example, I’m creating a POCO CustomerState to hold some customer data.

Then create a ICustomerGrain that just extends IStateHolderGrain where T is our POCO CustomerState.

Our concrete class CustomerGrain that implements that new ICustomerGrain.

Lastly I created a CustomerStateService which just contains some static methods that create and retrieve our POCO.


As per my previous post, I’m using ASP.NET Core with Botwin Middleware for a route endpoint.  From here I can use the CustomerStateService to create and fetch out our data.


One of the benefits is abstraction as we can have a POCO for our state that can be persisted to permanent storage.  There’s no dependency of Orleans in our POCO or Botwin Module.

Also we have an immediate consistent cache.  If we were to expose methods to modify the state, our grain would persist those to permanent storage when it decides and we are always returning the most up to date state.


If you want to try the demo, all the source is available on my PracticalOrleans GitHub Repo.

Do you have any questions or comments? Are you using Orleans?  I’d love to hear about it in the comments or on Twitter.

Enjoy this post? Subscribe!

Subscribe to our weekly Newsletter and stay tuned.

Microsoft Orleans Tutorial: Grains and Silos

Grains and SilosThis is the first post in the series were I’m actually getting into some code.  You will be able to follow along the journey of creating a practical web application using Microsoft Orleans.  This first post is really just setting the ground level to get familiar with the basics of Grains and Silos.  By the end of this post I’ll have a simple demo app that is a functioning ASP.NET Core as our client/frontend with a Orleans Silo hosting our Grains.

Blog Post Series:

Grains and Silos

For this blog post and throughout this series I’m going to be creating a web application with ASP.NET Core.   Our ASP.NET Core application will be our frontend and Orleans sits as a stateful middle tier in front of our data storage.

Now to break down the two pieces we need to get started with Orleans are Grains and Silos.  First let’s take a look at what Grains are.


Grains are the key primitives of the Orleans programming model. Grains are the building blocks of an Orleans application, they are atomic units of isolation, distribution, and persistence. Grains are objects that represent application entities. Just like in the classic Object Oriented Programming, a grain encapsulates state of an entity and encodes its behavior in the code logic. Grains can hold references to each other and interact by invoking each other’s methods exposed via interfaces.

One other interesting note about grains is that they are automatically managed by Orleans.  You don’t have to worry about instantiating or managing them.   Orleans terms them virtual actors as apposed to traditional actors.


Where do Grains live? Silos of course.

Silos are what host and execute Grains.  Again, Grains are your objects that expose behavior and encapsulate state.  Orleans creates your grains in the Silo and executes them here.  Your client code will reference only interfaces that your grains implement.  Don’t worry, sample code coming up.

Oh and of course, you can also have a cluster of silos.


Now that we know the basics, let’s create a really simple demo just to get our feet wet and get a fully functioning app running.

Note: Remember to BUILD once you create any project as there is some codegen that occurs.  Do this before you start freaking out about types missing.

Grains Project

First we are going to create a project called Grains for our grains.  Here’s a netstandard2.0 project with references to a couple Orleans packages.  Note as of this blog post, I’m using 2.0.0-beta2 which supports .NET Standard 2.0.

Now we can create our first Grain.  I’m going to create a grain that simply increments a number within the grain.  Yes that simple.

Silo Project

Now that we have a grain, we need a Silo.  Create a .NET Core 2.0 console application called Silo.  Here’s the cs project with the relevant NuGet packages as well as Reference to our Grains project.

As you can see, we also have a OrleansConfiguration.xml that needs to be included in the output.  This is configuration file we will use for hosting our Silo.

Lastly, we need to start our Silo in our Program.cs


Now let’s create a client that will interact with our Grains.  Create a new ASP.NET Core running .NET Core 2.0 application called Web

I’ve got a couple other dependencies referenced.  Botwin and Polly.

Polly is a fault handling library and Botwin is Middleware for ASP.NET Core that allows Nancy type routing.

The reason we want to use Polly is for our initial connection to the Silo.  Since we might running multiple projects from Visual Studio/Rider/Code/Whatever, this will help since the Silo might not be ready by the time our ASP.NET fires up.

Here is our Startup.cs that creates a singleton of our the Orleans IClusterClient.  It is thread-safe and intended to be used for the life of the application.

Now we can create a Botwin module to handle two different endpoints.  A GET request will return what our current count is, and a POST will increment our count by 1.

We simply inject our IClusterClient which is used to call GetGrain<T>.  Once we have our grain, we can call the relevant methods defined on the grain interface.


That is a fully functional, yet incredibly simple demo using Orleans on .NET Core and ASP.NET Core.  Stay tuned for more as we legitimately start building an app.

If you want to try the demo, all the source is available on my PracticalOrleans GitHub Repo.

Do you have any questions or comments? Are you using Orleans?  I’d love to hear about it in the comments or on Twitter.