How to use Orleans: grains, install and a first example

What Orleans is and who it is for

Orleans extends familiar .NET ideas such as objects, interfaces, async/await and try/catch to environments with multiple servers. The project describes itself as a cross-platform framework that scales from a single on-premises server to globally distributed applications in the cloud.

It suits C# and .NET developers building scalable backend services, teams that model many independent entities such as devices or users as stateful objects, and developers moving from single-server apps to distributed systems. The README does not describe other language bindings, so it is aimed at .NET projects.

Understand grains, the core building block

The fundamental building block in an Orleans application is a grain. A grain combines a user-defined identity, behavior and state. Its identity is a user-defined key, so a grain is always available for invocation whether or not it is currently loaded in memory.

Grains are invoked through strongly-typed interfaces (contracts), either by other grains or by external clients such as web frontends. Each grain is an instance of a class that implements one or more of these interfaces. The runtime activates grains on demand and removes unused ones from memory, so you can write code as if all grains were always in memory.

• Stable identity: the key that the caller uses to reach the grain
• Statefulness: state can be kept in memory while the grain is active
• Managed lifecycle: the runtime activates, deactivates and places grains

Model an entity with an interface and a grain class

The README's IoT example models each device as a grain that acts as a digital twin of the physical device. A simple thermostat is described by an interface that inherits from IGrainWithStringKey, and a separate interface can expose control operations on the same grain.

A single implementation class, ThermostatGrain, derives from Grain and implements both interfaces. Note that the README says this example does not persist its state; a fuller persistence example is linked from the docs.

Call a grain from a client

Web frontends and other external clients call grains using the Orleans client library, which manages network communication. A client obtains a grain reference by key and then invokes its methods like any other async call.

Clients can also be co-hosted in the same process as silos for simplicity.

Know how silos and the cluster fit together

The main component of the Orleans runtime is the silo, which hosts grains. Typically a group of silos runs as a cluster for scalability and fault tolerance. Silos coordinate to distribute work and to detect and recover from failures.

The silo also provides runtime services such as timers, reminders (persistent timers), persistence, transactions and streams. Orleans is compatible with .NET Standard 2.0 and above and runs on Windows, Linux and macOS, in full .NET Framework or .NET Core.

Use persistence and distributed transactions

Grains can hold several named persistent data objects, for example a profile and an inventory, and each can be stored in a different storage system. While a grain is running, its state is kept in memory; calling state.WriteStateAsync() ensures the backing store is updated.

Grains can also have transactional state. Multiple grains can take part in ACID transactions regardless of where their state is stored. These transactions are distributed and decentralized, with no central transaction manager, and use serializable isolation.