Client configuration

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

A client for connecting to a cluster of silos and sending requests to grains is configured 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.

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

There are several key aspects of client configuration:

• Orleans clustering information
• Clustering provider
• Application parts

Example of a client configuration:

var client = new HostBuilder()
    .UseOrleansClient((context, clientBuilder) =>
    {
        clientBuilder.Configure<ClusterOptions>(options =>
        {
            options.ClusterId = "my-first-cluster";
            options.ServiceId = "MyOrleansService";
        })
        .UseAzureStorageClustering(
            options => options.ConfigureTableServiceClient(
                context.Configuration["ORLEANS_AZURE_STORAGE_CONNECTION_STRING"]));
    })
    .Build();

using Orleans.Hosting;

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

Let's breakdown 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 silo that uses this ID will be able to directly talk to each other. Some will choose to use a different ClusterId for each deployments for example.
• the ClusterOptions.ServiceId to "AspNetSampleApp": this is a unique ID for your application, that will be used by some provider (for example for persistence providers). This ID should be stable (not change) across deployments.

Clustering provider

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

.UseAzureStorageClustering(
    options => options.ConnectionString = connectionString)

The client will discover all gateway available in the cluster using this provider. Several providers are available, here in this sample we use the Azure Table provider.

For more information, see Server configuration.

Application parts

.ConfigureApplicationParts(
    parts => parts.AddApplicationPart(
        typeof(IValueGrain).Assembly))
        .WithReferences())

For more information, see Server configuration.