DOCSEARCHbyAlgolia
Submit Docs

Microsoft Orleans Documentation

repository·main·Indexed 27 days ago

https://github.com/dotnet/orleans

A cross-platform framework for building robust, scalable distributed applications using the Virtual Actor Model. It enables the creation of distributed systems using .NET concepts like objects, interfaces, and async/await. Key features include grains (entities with identity, behavior, and state), silos for hosting grains, and an admin dashboard (orleans-dashboard-app) for development and testing.

Tokens
49.5K
Snippets
149
Records
204
Agent score
94%

What's inside Orleans

  1. Overview of Orleans Framework

    main
    Orleans is a cross-platform framework for building robust, scalable distributed applications using the Virtual Actor Model. It allows developers to build distributed systems using familiar .NET concepts like objects, interfaces, and async/await. Orleans scales from single on-premises servers to globally distributed cloud applications, providing elastic scalability and fault tolerance.

  2. Overview of Microsoft Orleans Dashboard Core features

    main

    The Microsoft.Orleans.Dashboard.Abstractions package includes the following core components for monitoring Orleans clusters:

    • Metrics Collection Services: Grain-based services that collect runtime statistics.
    • Data Models: Shared types for representing silo and grain statistics.
    • History Tracking: Time-series data storage for performance metrics.
    • Grain Profiling: Method-level performance tracking infrastructure.

  3. Explore Orleans Samples

    main
    The official collection of Orleans samples has been moved to the dotnet/samples repository. You can browse them via the Samples browser or access the source directly on GitHub. These samples cover a wide range of use cases from basic 'Hello World' applications to complex distributed systems involving transactions, streaming, and Kubernetes deployment.

  4. Understand the Orleans Runtime and Silos

    main

    The Orleans runtime implements the programming model.

    • Silo: The main component of the runtime responsible for hosting grains. Silos typically run in a cluster to provide scalability and fault tolerance.
    • Cluster: A group of silos that coordinate to distribute work and recover from failures. Grains in a cluster communicate as if they were in a single process.
    • Client Library: Used by external clients to call grains. It manages network communication automatically. Clients can be co-hosted in the same process as silos.

    Compatibility:

    • .NET Standard 2.0 and above.
    • Runs on Windows, Linux, and macOS.
    • Supports .NET Framework and .NET Core.

  5. Understand the Durable Job lifecycle

    main

    Jobs follow a specific lifecycle managed by the Orleans runtime:

    1. Scheduled: The job is created and added to a time-based shard.
    2. Waiting: The job resides in a queue until its DueTime is reached.
    3. Executing: The IDurableJobHandler.ExecuteJobAsync method is invoked on the target grain.
    4. Completion:
      • Success: The job is removed.
      • Failure: The ShouldRetry policy determines if the job is re-queued with a new due time or removed.

  7. Host the Orleans Dashboard in a separate web application

    main

    You can host the Orleans Dashboard in a standalone web application that connects to an Orleans cluster as a client, rather than co-hosting it within the silos. This separates the dashboard web service from your Orleans silos.

    Implementation Steps

    1. Configure the Silo: Ensure your silo is configured with appropriate endpoints and has AddDashboard() called in its configuration.
    2. Configure the Dashboard Client: In your web application, use UseOrleansClient to connect to the cluster gateways and call AddDashboard() to register the necessary services.
    3. Map Endpoints: Use MapOrleansDashboard() in your web application to expose the dashboard routes.
    WARNING

    The Orleans Dashboard is designed for development and testing scenarios only. It is not recommended for production deployments as it can have a significant performance impact on your cluster.

    // 1. Silo Configuration
var siloHost = Host.CreateDefaultBuilder(args)
    .UseOrleans((_, builder) =>
    {
        builder.UseDevelopmentClustering(options =>
            options.PrimarySiloEndpoint = new IPEndPoint(IPAddress.Loopback, 11111));
        builder.ConfigureEndpoints(IPAddress.Loopback, 11111, 30000);
        builder.AddDashboard();
    })
    .Build();

// 2. Dashboard Web App Configuration
var dashboardBuilder = WebApplication.CreateBuilder(args);

dashboardBuilder.UseOrleansClient(clientBuilder =>
{
    clientBuilder.UseStaticClustering(options =>
        options.Gateways.Add(new IPEndPoint(IPAddress.Loopback, 30000).ToGatewayUri()));

    clientBuilder.AddDashboard();
});

var app = dashboardBuilder.Build();

// 3. Map Endpoints
app.MapOrleansDashboard();

await app.RunAsync();

  8. Integrate Orleans Redis Persistence with .NET Aspire

    main

    When using .NET Aspire, use the .NET Aspire Redis integration for automatic service discovery and telemetry. In your AppHost, use .WithGrainStorage("storageName", redisResource) to link the Redis resource to your Orleans deployment.

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

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

var orleans = builder.AddOrleans("orleans")
    .WithGrainStorage("redisStore", redis);

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

builder.Build().Run();

  10. Cohost the Orleans Dashboard within an ASP.NET Core application

    main

    You can host the Orleans Dashboard within the same process as your Orleans silo using ASP.NET Core minimal APIs. This is the simplest setup for development and testing, allowing the dashboard to run on the same port as your web application.

    To implement this, follow these steps:

    1. Configure Orleans using builder.UseOrleans().
    2. Add the dashboard to the silo builder using siloBuilder.AddDashboard().
    3. Map the dashboard endpoints to the application using app.MapOrleansDashboard().
    var builder = WebApplication.CreateBuilder(args);

// Configure Orleans
builder.UseOrleans(siloBuilder =>
{
    siloBuilder.UseLocalhostClustering();
    siloBuilder.UseInMemoryReminderService();
    siloBuilder.AddMemoryGrainStorageAsDefault();

    // Add the dashboard
    siloBuilder.AddDashboard();
});

var app = builder.Build();

// Map dashboard endpoints
app.MapOrleansDashboard();

app.Run();