ContextQMD
Back to Orleans

Microsoft Orleans Grain Directory for Redis

src/Redis/Orleans.GrainDirectory.Redis/README.md

10.1.04.3 KB
Original Source

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:

shell
dotnet add package Microsoft.Orleans.GrainDirectory.Redis

Example - Configuring Redis Grain Directory

csharp
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

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

csharp
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:

csharp
// 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:

Feedback & Contributing