orleans

Cloud Native application framework for .NET

10,029

2,021

10,029

548

View on GitHub

Top Related Projects

service-fabric

3,020

Service Fabric is a distributed systems platform for packaging, deploying, and managing stateless and stateful distributed applications and containers at large scale.

akka

13,024

Build highly concurrent, distributed, and resilient message-driven applications on the JVM

dapr

23,812

Dapr is a portable, event-driven, runtime for building distributed applications across cloud and edge.

dubbo

40,335

The java implementation of Apache Dubbo. An RPC and microservice framework.

grpc

41,549

The C based gRPC (C++, Python, Ruby, Objective-C, PHP, C#)

Quick Overview

Orleans is a cross-platform framework for building robust, scalable distributed applications. It provides a straightforward approach to developing distributed systems by using virtual actor-based abstractions, allowing developers to write code as if it were for a single-threaded application while Orleans handles the complexities of distribution and concurrency.

Pros

Simplifies distributed system development with its virtual actor model
Offers automatic scalability and fault-tolerance
Provides a programming model that feels familiar to .NET developers
Supports both stateless and stateful services

Cons

Learning curve for developers new to actor-based programming
Can be overkill for simple applications that don't require distributed architecture
Limited ecosystem compared to some other distributed computing frameworks
Performance overhead for very small-scale applications

Code Examples

Defining a grain interface:

public interface IHelloGrain : IGrainWithStringKey
{
    Task<string> SayHello(string greeting);
}

Implementing a grain:

public class HelloGrain : Grain, IHelloGrain
{
    public Task<string> SayHello(string greeting)
    {
        return Task.FromResult($"Hello, {greeting}!");
    }
}

Calling a grain from a client:

var client = new ClientBuilder()
    .UseLocalhostClustering()
    .Build();

await client.Connect();
var grain = client.GetGrain<IHelloGrain>("user1");
var response = await grain.SayHello("World");
Console.WriteLine(response);

Getting Started

Install the Orleans NuGet packages:

dotnet add package Microsoft.Orleans.Server
dotnet add package Microsoft.Orleans.Client

Create a new console application and add the following code to Program.cs:

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Orleans;
using Orleans.Hosting;

await Host.CreateDefaultBuilder(args)
    .UseOrleans(builder =>
    {
        builder.UseLocalhostClustering();
    })
    .RunConsoleAsync();

Define your grain interfaces and implementations, then run the application to start the Orleans silo.

Competitor Comparisons

service-fabric

3,020

Service Fabric is a distributed systems platform for packaging, deploying, and managing stateless and stateful distributed applications and containers at large scale.

Pros of Service Fabric

More comprehensive platform for microservices, offering features like stateful services and reliable collections
Better support for heterogeneous environments, including Linux and containers
Stronger focus on orchestration and cluster management

Cons of Service Fabric

Steeper learning curve due to its complexity and broader feature set
More tightly coupled with Azure, potentially limiting flexibility in multi-cloud scenarios
Heavier resource footprint compared to Orleans' lightweight approach

Code Comparison

Orleans:

public class MyGrain : Grain, IMyGrain
{
    public Task<string> SayHello(string greeting)
    {
        return Task.FromResult($"Hello, {greeting}!");
    }
}

Service Fabric:

public class MyStatefulService : StatefulService
{
    protected override async Task RunAsync(CancellationToken cancellationToken)
    {
        while (true)
        {
            cancellationToken.ThrowIfCancellationRequested();
            await Task.Delay(TimeSpan.FromSeconds(1), cancellationToken);
        }
    }
}

Summary

Service Fabric offers a more comprehensive platform for microservices with stronger orchestration capabilities, while Orleans provides a simpler, lightweight approach focused on distributed virtual actor model. Service Fabric has a broader feature set but comes with increased complexity, while Orleans offers easier adoption but may lack some advanced features for complex distributed systems.

akka

13,024

Build highly concurrent, distributed, and resilient message-driven applications on the JVM

Pros of Akka

Multi-language support: Akka is available for both Java and Scala, offering flexibility for developers
Mature ecosystem: Akka has a longer history and a more extensive set of tools and libraries
Strong focus on reactive programming: Built-in support for reactive streams and backpressure handling

Cons of Akka

Steeper learning curve: Akka's actor model and concepts can be more challenging for newcomers
Less integrated with cloud services: Orleans has better out-of-the-box integration with cloud platforms
Configuration complexity: Akka often requires more detailed configuration for optimal performance

Code Comparison

Akka (Scala):

class MyActor extends Actor {
  def receive = {
    case "hello" => println("Hello, Akka!")
    case _ => println("Unknown message")
  }
}

Orleans (C#):

public class MyGrain : Grain, IMyGrain
{
    public Task SayHello()
    {
        Console.WriteLine("Hello, Orleans!");
        return Task.CompletedTask;
    }
}

Both frameworks use actor-like models, but Orleans abstracts away more complexity with its grain-based approach, while Akka provides more fine-grained control over actor behavior.

dapr

23,812

Dapr is a portable, event-driven, runtime for building distributed applications across cloud and edge.

Pros of Dapr

Language-agnostic, supporting multiple programming languages and frameworks
Modular architecture with pluggable components for various cloud services
Easier integration with cloud-native technologies and microservices

Cons of Dapr

Relatively newer project with a smaller community compared to Orleans
May require additional setup and configuration for complex scenarios
Less specialized for distributed computing patterns than Orleans

Code Comparison

Orleans:

public class MyGrain : Grain, IMyGrain
{
    public Task<string> SayHello(string greeting)
    {
        return Task.FromResult($"Hello, {greeting}!");
    }
}

Dapr:

@app.route('/hello')
def hello():
    return 'Hello, World!'

app.run(port=3000)

Summary

Orleans is a specialized framework for building distributed systems in .NET, while Dapr is a more general-purpose, language-agnostic runtime for building microservices. Orleans excels in scenarios requiring complex distributed computing patterns, whereas Dapr shines in multi-language environments and cloud-native integrations. The choice between the two depends on specific project requirements, team expertise, and the desired level of abstraction for distributed system development.

temporal

11,289

Temporal service

Pros of Temporal

Language-agnostic with SDKs for multiple programming languages
Built-in support for distributed tracing and observability
More flexible workflow orchestration with support for dynamic workflows

Cons of Temporal

Steeper learning curve due to more complex concepts and abstractions
Requires additional infrastructure setup and management
Less integrated with .NET ecosystem compared to Orleans

Code Comparison

Orleans:

public class MyGrain : Grain, IMyGrain
{
    public Task DoSomething()
    {
        // Grain implementation
    }
}

Temporal:

func MyWorkflow(ctx workflow.Context) error {
    // Workflow implementation
    return nil
}

Summary

Orleans and Temporal are both distributed computing frameworks, but they have different focuses. Orleans is tailored for .NET developers and provides a simpler programming model based on virtual actors (grains). Temporal offers a more flexible workflow orchestration system that supports multiple languages but requires more setup and has a steeper learning curve. Orleans integrates well with the .NET ecosystem, while Temporal provides better built-in observability and tracing capabilities. The choice between them depends on your specific requirements, language preferences, and the complexity of your distributed workflows.

dubbo

40,335

The java implementation of Apache Dubbo. An RPC and microservice framework.

Pros of Dubbo

Multi-language support: Dubbo supports Java, Go, Node.js, Python, and more
Extensive service governance features: Load balancing, routing, and service discovery
Strong ecosystem with various extensions and integrations

Cons of Dubbo

Steeper learning curve compared to Orleans
Less focus on actor model and virtual actor abstractions
More complex configuration and setup process

Code Comparison

Orleans (C#):

public interface IHello : IGrainWithIntegerKey
{
    Task<string> SayHello(string greeting);
}

public class HelloGrain : Grain, IHello
{
    public Task<string> SayHello(string greeting)
    {
        return Task.FromResult($"Hello, {greeting}!");
    }
}

Dubbo (Java):

public interface HelloService {
    String sayHello(String name);
}

@Service
public class HelloServiceImpl implements HelloService {
    public String sayHello(String name) {
        return "Hello " + name;
    }
}

Both frameworks provide ways to define and implement services, but Orleans uses the actor model with grains, while Dubbo follows a more traditional RPC approach. Orleans offers a more straightforward programming model for distributed systems, while Dubbo provides more flexibility and language options.

grpc

41,549

The C based gRPC (C++, Python, Ruby, Objective-C, PHP, C#)

Pros of gRPC

Language-agnostic: Supports multiple programming languages, allowing for easier cross-platform development
Efficient binary serialization: Uses Protocol Buffers for faster data transfer and smaller payload sizes
Built-in streaming support: Offers unary, server streaming, client streaming, and bidirectional streaming

Cons of gRPC

Steeper learning curve: Requires understanding of Protocol Buffers and gRPC concepts
Limited browser support: Not natively supported in web browsers, requiring additional tools or proxies

Code Comparison

gRPC (Protocol Buffer definition):

syntax = "proto3";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

Orleans (Grain interface):

public interface IHelloGrain : IGrainWithStringKey
{
    Task<string> SayHello(string name);
}

Summary

While gRPC excels in cross-platform communication and efficient data transfer, Orleans focuses on building distributed systems with virtual actor model abstractions. gRPC offers more flexibility in language support, while Orleans provides a simpler programming model for .NET developers building scalable applications.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Orleans logo

Orleans is a cross-platform framework for building robust, scalable distributed applications

Orleans builds on the developer productivity of .NET and brings it to the world of distributed applications, such as cloud services. Orleans scales from a single on-premises server to globally distributed, highly-available applications in the cloud.

Orleans takes familiar concepts like objects, interfaces, async/await, and try/catch and extends them to multi-server environments. As such, it helps developers experienced with single-server applications transition to building resilient, scalable cloud services and other distributed applications. For this reason, Orleans has often been referred to as "Distributed .NET".

It was created by Microsoft Research and introduced the Virtual Actor Model as a novel approach to building a new generation of distributed systems for the Cloud era. The core contribution of Orleans is its programming model which tames the complexity inherent to highly-parallel distributed systems without restricting capabilities or imposing onerous constraints on the developer.

Grains

A grain is composed of a stable identity, behavior, and state

The fundamental building block in any Orleans application is a grain. Grains are entities comprising user-defined identity, behavior, and state. Grain identities are user-defined keys which make Grains always available for invocation. Grains can be invoked by other grains or by external clients such as Web frontends, via strongly-typed communication interfaces (contracts). Each grain is an instance of a class which implements one or more of these interfaces.

Grains can have volatile and/or persistent state that can be stored in any storage system. As such, grains implicitly partition application state, enabling automatic scalability and simplifying recovery from failures. Grain state is kept in memory while the grain is active, leading to lower latency and less load on data stores.

A diagram showing the managed lifecycle of a grain

Instantiation of grains is automatically performed on demand by the Orleans runtime. Grains which are not used for a while are automatically removed from memory to free up resources. This is possible because of their stable identity, which allows invoking grains whether they are already loaded into memory or not. This also allows for transparent recovery from failure because the caller does not need to know on which server a grain is instantiated on at any point in time. Grains have a managed lifecycle, with the Orleans runtime responsible for activating/deactivating, and placing/locating grains as needed. This allows the developer to write code as if all grains were always in-memory.

Taken together, the stable identity, statefulness, and managed lifecycle of Grains are core factors that make systems built on Orleans scalable, performant, & reliable without forcing developers to write complex distributed systems code.

Example: IoT cloud backend

Consider a cloud backend for an Internet of Things system. This application needs to process incoming device data, filter, aggregate, and process this information, and enable sending commands to devices. In Orleans, it is natural to model each device with a grain which becomes a digital twin of the physical device it corresponds to. These grains keep the latest device data in memory, so that they can be quickly queried and processed without the need to communicate with the physical device directly. By observing streams of time-series data from the device, the grain can detect changes in conditions, such as measurements exceeding a threshold, and trigger an action.

A simple thermostat could be modeled as follows:

public interface IThermostat : IGrainWithStringKey
{
    Task<List<Command>> OnUpdate(ThermostatStatus update);
}

Events arriving from the thermostat from a Web frontend can be sent to its grain by invoking the OnUpdate method which optionally returns a command back to the device.

var thermostat = client.GetGrain<IThermostat>(id);
return await thermostat.OnUpdate(update);

The same thermostat grain can implement a separate interface for control systems to interact with:

public interface IThermostatControl : IGrainWithStringKey
{
    Task<ThermostatStatus> GetStatus();

    Task UpdateConfiguration(ThermostatConfiguration config);
}

These two interfaces (IThermostat and IThermostatControl) are implemented by a single implementation class:

public class ThermostatGrain : Grain, IThermostat, IThermostatControl
{
    private ThermostatStatus _status;
    private List<Command> _commands;

    public Task<List<Command>> OnUpdate(ThermostatStatus status)
    {
        _status = status;
        var result = _commands;
        _commands = new List<Command>();
        return Task.FromResult(result);
    }
    
    public Task<ThermostatStatus> GetStatus() => Task.FromResult(_status);
    
    public Task UpdateConfiguration(ThermostatConfiguration config)
    {
        _commands.Add(new ConfigUpdateCommand(config));
        return Task.CompletedTask;
    }
}

The Grain class above does not persist its state. A more thorough example demonstrating state persistence is available in the docs, for more information see Microsoft Orleans: Grain Persistence.

Orleans runtime

The Orleans runtime is what implements the programming model for applications. The main component of the runtime is the silo, which is responsible for hosting grains. Typically, a group of silos run as a cluster for scalability and fault-tolerance. When run as a cluster, silos coordinate with each other to distribute work, detect and recover from failures. The runtime enables grains hosted in the cluster to communicate with each other as if they are within a single process.

In addition to the core programming model, the silo provides grains with a set of runtime services, such as timers, reminders (persistent timers), persistence, transactions, streams, and more. See the features section below for more detail.

Web frontends and other external clients call grains in the cluster using the client library which automatically manages network communication. Clients can also be co-hosted in the same process with silos for simplicity.

Orleans is compatible with .NET Standard 2.0 and above, running on Windows, Linux, and macOS, in full .NET Framework or .NET Core.

Features

Orleans is a feature-rich framework. It provides a set of services that enable the development of distributed systems. The following sections describe the features of Orleans.

Persistence

Orleans provides a simple persistence model which ensures that state is available to a grain before requests are processed and that consistency is maintained. Grains can have multiple named persistent data objects, for example, one called "profile" for a user's profile and one called "inventory" for their inventory. This state can be stored in any storage system. For example, profile data may be stored in one database and inventory in another. While a grain is running, this state is kept in memory so that read requests can be served without accessing storage. When the grain updates its state, a state.WriteStateAsync() call ensures that the backing store is updated for durability and consistency. For more information see Microsoft Orleans: Grain Persistence.

Distributed ACID transactions

In addition to the simple persistence model described above, grains can have transactional state. Multiple grains can participate in ACID transactions together regardless of where their state is ultimately stored. Transactions in Orleans are distributed and decentralized (there is no central transaction manager or transaction coordinator) and have serializable isolation. For more information, see the Microsoft Orleans: Transactions.

Streams

Streams help developers to process series of data items in near-real time. Streams in Orleans are managed: streams do not need to be created or registered before a grain or client publishes to a stream or subscribes to a stream. This allows for greater decoupling of stream producers and consumers from each other and from the infrastructure. Stream processing is reliable: grains can store checkpoints (cursors) and reset to a stored checkpoint during activation or at any point afterwards.

Streams supports batch delivery of messages to consumers to improve efficiency and recovery performance. Streams are backed by queueing services such as Azure Event Hubs, Amazon Kinesis, and others. An arbitrary number of streams can be multiplexed onto a smaller number of queues and the responsibility for processing these queues is balanced evenly across the cluster.

Timers & reminders

Reminders are a durable scheduling mechanism for grains. They can be used to ensure that some action is completed at a future point even if the grain is not currently activated at that time. Timers are the non-durable counterpart to reminders and can be used for high-frequency events which do not require reliability. For more information, see Microsoft Orleans: Timers and reminders.

Flexible grain placement

When a grain is activated in Orleans, the runtime decides which server (silo) to activate that grain on. This is called grain placement. The placement process in Orleans is fully configurable: developers can choose from a set of out-of-the-box placement policies such as random, prefer-local, and load-based, or custom logic can be configured. This allows for full flexibility in deciding where grains are created. For example, grains can be placed on a server close to resources which they need to operate on or other grains which they communicate with.

Grain versioning & heterogeneous clusters

Application code evolves over time and upgrading live, production systems in a manner which safely accounts for these changes can be challenging, particularly in stateful systems. Grain interfaces in Orleans can be optionally versioned. The cluster maintains a mapping of which grain implementations are available on which silos in the cluster and the versions of those implementations. This version information is used by the runtime in conjunction with placement strategies to make placement decisions when routing calls to grains. In addition to safe update of versioned grains, this also enables heterogeneous clusters, where different silos have different sets of grain implementations available. For more information, see Microsoft Orleans: Grain interface versioning.

Elastic scalability & fault tolerance

Orleans is designed to scale elastically. When a silo joins a cluster it is able to accept new activations and when a silo leaves the cluster (either because of scale down or a machine failure) the grains which were activated on that silo will be re-activated on remaining silos as needed. An Orleans cluster can be scaled down to a single silo. The same properties which enable elastic scalability also enable fault tolerance: the cluster automatically detects and quickly recovers from failures.

Run anywhere

Orleans runs anywhere that .NET Core or .NET Framework are supported. This includes hosting on Linux, Windows, and macOS and deploying to Kubernetes, virtual or physical machines, on premises or in the cloud, and PaaS services such as Azure Cloud Services.

Stateless workers

Stateless workers are specially marked grains which do not have any associated state and can be activated on multiple silos simultaneously. This enables increased parallelism for stateless functions. For more information, see Microsoft Orleans: Stateless worker grains documentation.

Grain call filters

Logic which is common to many grains can be expressed as an interceptor, or Grain call filter. Orleans supports filters for both incoming and outgoing calls. Some common use-cases of filters are: authorization, logging and telemetry, and error handling.

Request context

Metadata and other information can be passed along a series of requests using request context. Request context can be used for holding distributed tracing information or any other user-defined values.

Documentation

The official documentation for Microsoft Orleans is available at https://docs.microsoft.com/dotnet/orleans.

Samples

A variety of samples are available in the official .NET Samples Browser.

Get started

Please see the getting started tutorial.

Building

On Windows, run the build.cmd script to build the NuGet packages locally, then reference the required NuGet packages from /Artifacts/Release/*. You can run Test.cmd to run all BVT tests, and TestAll.cmd to also run Functional tests.

On Linux and macOS, run dotnet build to build Orleans.

Official builds

The latest stable, production-quality release is located here.

Nightly builds are published to a NuGet feed. These builds pass all functional tests, but are not thoroughly tested as the stable builds or pre-release builds published to NuGet.

Using the nightly build packages in your project

To use nightly builds in your project, add the MyGet feed using either of the following methods:

Changing the .csproj file to include this section:

<ItemGroup>
  <RestoreSources>
    $(RestoreSources);
    https://pkgs.dev.azure.com/dnceng/public/_packaging/orleans-nightly/nuget/v3/index.json
  </RestoreSources>
</ItemGroup>

Creating a NuGet.config file in the solution directory with the following contents:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear /> 
    <add key="orleans-nightly" value="https://pkgs.dev.azure.com/dnceng/public/_packaging/orleans-nightly/nuget/v3/index.json" />
    <add key="nuget" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
</configuration>

Community

Ask questions by opening an issue on GitHub or on Stack Overflow
Chat on Discord
Follow the @msftorleans Twitter account for Orleans announcements.
OrleansContrib - GitHub organization for community add-ons to Orleans Various community projects, including Monitoring, Design Patterns, Storage Providers, etc.
Guidelines for developers wanting to contribute code changes to Orleans.
You are also encouraged to report bugs or start a technical discussion by starting a new thread on GitHub.

License

This project is licensed under the MIT license.

Quick links

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot