Microsoft.Orleans.GrainDirectory.Redis

Microsoft Orleans Grain Directory for Redis

Introduction

Microsoft Orleans Grain Directory for Redis provides a grain directory implementation using Redis. The grain directory is used to locate active grain instances across the cluster, and this package allows Orleans to store that information in Redis.

Getting Started

To use this package, install it via NuGet:

dotnet add package Microsoft.Orleans.GrainDirectory.Redis

Example - Configuring Redis Grain Directory

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

var builder = Host.CreateApplicationBuilder(args)
    .UseOrleans(siloBuilder =>
    {
        siloBuilder
            .UseLocalhostClustering()
            // Configure Redis as the grain directory
            .UseRedisGrainDirectoryAsDefault(options =>
            {
                options.ConnectionString = "localhost:6379";
                options.Database = 0;
            });
    });

// Run the host
await builder.RunAsync();

Configuration via Microsoft.Extensions.Configuration

You can configure Orleans Redis grain directory using Microsoft.Extensions.Configuration (such as appsettings.json) instead of configuring it in code. When using this approach, Orleans will automatically read the configuration from the Orleans section.

Note: You can use either "ProviderType": "Redis" or "ProviderType": "AzureRedisCache" - both are supported and functionally equivalent.

Example - appsettings.json

{
  "ConnectionStrings": {
    "redis": "localhost:6379"
  },
  "Orleans": {
    "ClusterId": "my-cluster",
    "ServiceId": "MyOrleansService",
    "GrainDirectory": {
      "Default": {
        "ProviderType": "Redis",
        "ServiceKey": "redis"
      }
    }
  }
}

.NET Aspire Integration

For applications using .NET Aspire, consider using the .NET Aspire Redis integration which provides simplified Redis configuration, automatic service discovery, health checks, and telemetry. The Aspire integration automatically configures connection strings that Orleans can consume via the configuration system.

Example - Program.cs with Aspire Redis Integration

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

var builder = Host.CreateApplicationBuilder(args);

// Add service defaults (Aspire configurations)
builder.AddServiceDefaults();

// Add Redis via Aspire client integration
builder.AddKeyedRedisClient("redis");

// Add Orleans
builder.UseOrleans();

var host = builder.Build();
await host.StartAsync();

// Get a reference to a grain and call it
var client = host.Services.GetRequiredService<IClusterClient>();
var grain = client.GetGrain<IMyGrain>("user123");
var response = await grain.SayHello("Aspire Redis Grain Directory");

Console.WriteLine($"Grain response: {response}");
await host.WaitForShutdownAsync();

This example assumes your AppHost project has configured Redis like this:

// In your AppHost/Program.cs
var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.AddRedis("redis");

var orleans = builder.AddOrleans("orleans")
    .WithGrainDirectory("Default", redis);

builder.AddProject<Projects.MyOrleansApp>("orleans-app")
    .WithReference(orleans);

builder.Build().Run();

Documentation

For more comprehensive documentation, please refer to:

• Microsoft Orleans Documentation
• Configuration Guide
• Implementation Details
• Redis Documentation

Feedback & Contributing

• If you have any issues or would like to provide feedback, please open an issue on GitHub
• Join our community on Discord
• Follow the @msftorleans Twitter account for Orleans announcements
• Contributions are welcome! Please review our contribution guidelines
• This project is licensed under the MIT license