Orleans grain directory

Grains have stable logical identities. They can activate (instantiate) and deactivate many times over the application's life, but at most one activation of a grain exists at any point in time. Each time a grain activates, it might be placed on a different silo in the cluster. When a grain activates in the cluster, it registers itself in the grain directory. This ensures subsequent invocations of that grain are delivered to that activation and prevents the creation of other activations (instances) of that grain. The grain directory is responsible for maintaining a mapping between a grain identity and the location (which silo) of its current activation.

You can configure which grain directory implementation to use on a per-grain type basis, and you can even inject your implementation.

Which grain directory should you use?

We recommend always starting with the default directory (the built-in distributed in-cluster directory). Although it's eventually consistent and allows occasional duplicate activations when the cluster is unstable, the built-in directory is self-sufficient, has no external dependencies, requires no configuration, and has been used successfully in production since the beginning.

When you have some experience with Orleans and have a use case requiring a stronger single-activation guarantee, or if you want to minimize the number of grains deactivated when a silo shuts down, consider using a storage-based grain directory implementation, such as the Redis implementation. Try using it for one or a few grain types first, starting with those that are long-lived, have significant state, or have an expensive initialization process.

// Use as the default grain directory
builder.AddDistributedGrainDirectory();

// Or add as a named directory
builder.AddDistributedGrainDirectory("MyDistributedDirectory");

dotnet add package Microsoft.Orleans.GrainDirectory.AdoNet

// Use as the default grain directory
builder.UseAdoNetGrainDirectoryAsDefault(options =>
{
    options.Invariant = "System.Data.SqlClient"; // or "Npgsql", "MySql.Data.MySqlClient"
    options.ConnectionString = "Server=localhost;Database=Orleans;...";
});

// Or add as a named directory
builder.AddAdoNetGrainDirectory("MyAdoNetDirectory", options =>
{
    options.Invariant = "Npgsql";
    options.ConnectionString = "Host=localhost;Database=Orleans;...";
});

Configuration

By default, you don't need to do anything; Orleans automatically uses the in-cluster grain directory and partitions it across the cluster. If you want to use a non-default grain directory configuration, you need to specify the name of the directory plugin to use. You can do this via an attribute on the grain class and by configuring the directory plugin with that name using dependency injection during silo configuration.

Grain configuration

Specify the grain directory plugin name using the GrainDirectoryAttribute:

[GrainDirectory(GrainDirectoryName = "my-grain-directory")]
public class MyGrain : Grain, IMyGrain
{
    // ...
}

Silo configuration

Here's how you configure the Redis grain directory implementation:

siloBuilder.AddRedisGrainDirectory(
    "my-grain-directory",
    options => options.ConfigurationOptions = redisConfiguration);

Configure the Azure grain directory like this:

siloBuilder.AddAzureTableGrainDirectory(
    "my-grain-directory",
    options => options.ConnectionString = azureConnectionString);

You can configure multiple directories with different names for use with different grain classes:

siloBuilder
    .AddRedisGrainDirectory(
        "redis-directory-1",
        options => options.ConfigurationOptions = redisConfiguration1)
    .AddRedisGrainDirectory(
        "redis-directory-2",
        options => options.ConfigurationOptions = redisConfiguration2)
    .AddAzureTableGrainDirectory(
        "azure-directory",
        options => options.ConnectionString = azureConnectionString);