Orleans configuration guide

Orleans uses the .NET Generic Host, dependency injection, and the .NET options pattern. Start with one of these hosting models:

Model	Use it when	Entry point
Silo with co-hosted client	The process hosts grains and also calls grains. This is the default for most services.	builder.UseOrleans(...)
External client	A separate process, such as a web frontend, calls a remote Orleans cluster but doesn’t host grains.	builder.UseOrleansClient(...)
Aspire-orchestrated application	Aspire creates backing resources and injects Orleans configuration and service references.	builder.AddOrleans(...) in the AppHost, then parameterless UseOrleans() or UseOrleansClient()

For a first local process, see Local development configuration. For production, configure silos and external clients with the same cluster identity and clustering provider:

• Server configuration
• Client configuration
• Typical configurations
• Orleans and Aspire integration

Programmatic configuration

Create the .NET Generic Host with CreateApplicationBuilder, call UseOrleans to add a silo, then build and run the host:

public static async Task RunSilo(string[] args)
{
    var builder = Host.CreateApplicationBuilder(args);

    builder.UseOrleans(siloBuilder =>
    {
        // Configure Orleans.
    });

    await builder.Build().RunAsync();
}

Starting the host starts the silo and its co-hosted IClusterClient. The client is available through dependency injection, and stopping the host coordinates a graceful Orleans shutdown.

Configure the silo through the ISiloBuilder passed to UseOrleans. External client processes use UseOrleansClient and configure the IClientBuilder passed to it. Provider extension methods validate configuration when the host starts. Programmatic configuration supports credentials supplied as SDK objects such as TokenCredential, computed configuration, and compile-time API discovery.

See Server configuration and Client configuration for compiled examples.

Declarative configuration

Orleans automatically binds the Orleans configuration section when UseOrleans or UseOrleansClient is called. The following sections are recognized:

Path	Applies to	Purpose
Orleans	Silo and client	ClusterOptions, including ServiceId and ClusterId
Orleans:Name	Silo	Silo name
Orleans:Messaging	Silo and client	SiloMessagingOptions or ClientMessagingOptions
Orleans:Gateway	Client	Gateway refresh and connection behavior
Orleans:Endpoints	Silo	Advertised and listening endpoints
Orleans:Clustering	Silo and client	One clustering provider
Orleans:Reminders	Silo	One reminder provider
Orleans:BroadcastChannel:{name}	Silo and client	Named broadcast-channel providers
Orleans:Streaming:{name}	Silo and client	Named stream providers
Orleans:GrainStorage:{name}	Silo	Named grain storage providers
Orleans:GrainDirectory:{name}	Silo	Named grain directory providers

A provider section selects a registered provider with ProviderType. Install the provider’s NuGet package so its configuration builder is discoverable. See Server configuration for the provider catalog and Typical configurations for deployment-oriented examples.

Environment variables use double underscores, for example Orleans__ClusterId and Orleans__Endpoints__SiloPort.

Note

Declarative provider names come from the installed provider assemblies. If Orleans reports an unknown ProviderType, verify that the corresponding package is referenced and use the provider name documented by that package.

Configuration precedence

The Generic Host combines .NET configuration providers in its normal order. Programmatic options configuration also participates in the options pipeline, so avoid configuring the same value in multiple places unless the override is intentional. Keep service and cluster identity stable and inject environment-specific endpoints, credentials, and provider connection details at deployment time.

Production checklist

• Use a durable, shared clustering provider; don’t use development or static clustering for a production cluster.
• Give every silo and client the same ServiceId, ClusterId, and clustering provider settings.
• Advertise addresses reachable by other silos and clients, especially behind NAT, containers, or load balancers.
• Use durable reminder and grain storage providers when the application depends on those features.
• Review Orleans security responsibilities and trust boundaries.
• Configure server garbage collection.
• Allow the Generic Host to perform graceful shutdown.
• Validate provider connectivity and credentials before rollout.

For option types and API entry points, see Core configuration options and Configuration.

For task-oriented configuration recipes, see the Orleans how-to guide index. For the exact signatures and defaults of configuration APIs, use the C# API reference.