Client configuration

Applies to: Orleans 7.0, Orleans 8.0, Orleans 9.0, Orleans 10.0

Configure a client for connecting to a cluster of silos and sending requests to grains programmatically via an IHostBuilder and several supplemental option classes. Like silo options, client option classes follow the Options pattern in .NET.

Applies to: Orleans 3.x

Configure a client for connecting to a cluster of silos and sending requests to grains programmatically via an ClientBuilder and several supplemental option classes. Like silo options, client option classes follow the Options pattern in .NET.

Tip

If you just want to start a local silo and a local client for development purposes, see Local development configuration.

Applies to: Orleans 8.0, Orleans 9.0, Orleans 10.0

Tip

If you’re using Aspire, client configuration is handled automatically. Aspire injects ClusterId, ServiceId, and clustering provider settings via environment variables, so you can use the simpler parameterless UseOrleansClient method. See Orleans and Aspire integration for the recommended approach.

Add the Microsoft.Orleans.Clustering.AzureStorage NuGet package to your client project.

There are several key aspects of client configuration:

• Orleans clustering information
• Clustering provider
• Application parts

Example of a client configuration:

Applies to: Orleans 7.0, Orleans 8.0, Orleans 9.0, Orleans 10.0

Microsoft Entra ID (recommended)

Using a TokenCredential with a service URI is the recommended approach. This pattern avoids storing secrets in configuration and leverages Microsoft Entra ID for secure authentication.

DefaultAzureCredential provides a credential chain that works seamlessly across local development and production environments. During development, it uses your Azure CLI or Visual Studio credentials. In production on Azure, it automatically uses the managed identity assigned to your resource.

Tip

DefaultAzureCredential works seamlessly across local development and production. In development, it uses your Azure CLI or Visual Studio credentials. In production on Azure, it automatically uses the resource’s managed identity. For improved performance and debuggability in production, consider replacing it with a specific credential like ManagedIdentityCredential. For more information, see Usage guidance for DefaultAzureCredential.

using Azure.Identity;

var builder = Host.CreateApplicationBuilder(args);
builder.UseOrleansClient(clientBuilder =>
{
    clientBuilder.Configure<ClusterOptions>(options =>
    {
        options.ClusterId = "my-first-cluster";
        options.ServiceId = "MyOrleansService";
    })
    .UseAzureStorageClustering(options =>
    {
        options.ConfigureTableServiceClient(
            new Uri("https://<your-storage-account>.table.core.windows.net"),
            new DefaultAzureCredential());
    });
});

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

Connection string

var builder = Host.CreateApplicationBuilder(args);
builder.UseOrleansClient(clientBuilder =>
{
    clientBuilder.Configure<ClusterOptions>(options =>
    {
        options.ClusterId = "my-first-cluster";
        options.ServiceId = "MyOrleansService";
    })
    .UseAzureStorageClustering(
        options => options.ConfigureTableServiceClient(
            builder.Configuration["ORLEANS_AZURE_STORAGE_CONNECTION_STRING"]));
});

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

---

Applies to: Orleans 3.x

public static async Task ConfigureClient(string connectionString)
{
    var client = new ClientBuilder()
        .Configure<ClusterOptions>(options =>
        {
            options.ClusterId = "my-first-cluster";
            options.ServiceId = "MyOrleansService";
        })
        .UseAzureStorageClustering(
            options => options.ConfigureTableServiceClient(connectionString))
        .ConfigureApplicationParts(
            parts => parts.AddApplicationPart(
                typeof(IValueGrain).Assembly))
        .Build();

    await client.Connect();
}

Let’s break down the steps used in this sample:

Orleans clustering information

    .Configure<ClusterOptions>(options =>
    {
        options.ClusterId = "orleans-docker";
        options.ServiceId = "AspNetSampleApp";
    })

Here, we set two things:

• The ClusterOptions.ClusterId to "my-first-cluster": This is a unique ID for the Orleans cluster. All clients and silos using this ID can directly talk to each other. Some might choose to use a different ClusterId for each deployment, for example.
• The ClusterOptions.ServiceId to "AspNetSampleApp": This is a unique ID for your application, used by some providers (e.g., persistence providers). This ID should remain stable across deployments.

Clustering provider

Applies to: Orleans 7.0, Orleans 8.0, Orleans 9.0, Orleans 10.0

Microsoft Entra ID (recommended)

Tip

DefaultAzureCredential works seamlessly across local development and production. In development, it uses your Azure CLI or Visual Studio credentials. In production on Azure, it automatically uses the resource’s managed identity. For improved performance and debuggability in production, consider replacing it with a specific credential like ManagedIdentityCredential. For more information, see Usage guidance for DefaultAzureCredential.

clientBuilder.UseAzureStorageClustering(options =>
{
    options.ConfigureTableServiceClient(
        new Uri("https://<your-storage-account>.table.core.windows.net"),
        new DefaultAzureCredential());
});

Connection string

.UseAzureStorageClustering(
    options => options.ConfigureTableServiceClient(connectionString));

---

Applies to: Orleans 3.x

public static void ConfigureAzureClustering(IClientBuilder clientBuilder, string connectionString)
{
    clientBuilder.UseAzureStorageClustering(
        options => options.ConfigureTableServiceClient(connectionString));
}

The client discovers all available gateways in the cluster using this provider. Several providers are available; here, we use the Azure Table provider.

For more information, see Server configuration.

Applies to: Orleans 3.x

Application parts

public static void ConfigureApplicationParts(IClientBuilder clientBuilder)
{
    clientBuilder.ConfigureApplicationParts(
        parts => parts.AddApplicationPart(
            typeof(IValueGrain).Assembly)
            .WithReferences());
}

For more information, see Server configuration.