Azure Storage grain persistence

The Azure Storage grain persistence provider supports both Azure Blob Storage and Azure Table Storage.

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

Configure Azure Table Storage

Install the Microsoft.Orleans.Persistence.AzureStorage package from NuGet. The Azure Table Storage provider stores state in a table row, splitting the state across multiple columns if it exceeds the limits of a single column. Each row can hold a maximum of 1 megabyte, as imposed by Azure Table Storage.

Configure the Azure Table Storage grain persistence provider using the AzureTableSiloBuilderExtensions.AddAzureTableGrainStorage extension method.

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;

siloBuilder.AddAzureTableGrainStorage(
    name: "profileStore",
    configureOptions: options =>
    {
        options.ConfigureTableServiceClient(
            new Uri("https://<your-storage-account>.table.core.windows.net"),
            new DefaultAzureCredential());
    });

Connection string

Warning

Connection strings contain secrets and should be avoided in production. Use Microsoft Entra ID authentication whenever possible.

siloBuilder.AddAzureTableGrainStorage(
    name: "profileStore",
    configureOptions: options =>
    {
        options.ConfigureTableServiceClient(
            "DefaultEndpointsProtocol=https;AccountName=data1;AccountKey=SOMETHING1");
    });

---

Configure Azure Blob Storage

The Azure Blob Storage provider stores state in a blob.

Configure the Azure Blob Storage grain persistence provider using the AzureBlobSiloBuilderExtensions.AddAzureBlobGrainStorage extension method.

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.

using Azure.Identity;

siloBuilder.AddAzureBlobGrainStorage(
    name: "profileStore",
    configureOptions: options =>
    {
        options.ConfigureBlobServiceClient(
            new Uri("https://<your-storage-account>.blob.core.windows.net"),
            new DefaultAzureCredential());
    });

Connection string

siloBuilder.AddAzureBlobGrainStorage(
    name: "profileStore",
    configureOptions: options =>
    {
        options.ConfigureBlobServiceClient(
             "DefaultEndpointsProtocol=https;AccountName=data1;AccountKey=SOMETHING1");
    });

---

Applies to: Orleans 8.0, Orleans 9.0, Orleans 10.0

Aspire integration for grain persistence

Aspire simplifies Azure Storage grain persistence configuration by managing resource provisioning and connection automatically.

Azure Blob Storage with Aspire

AppHost project (Program.cs):

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");
var blobs = storage.AddBlobs("grainstate");

var orleans = builder.AddOrleans("cluster")
    .WithClustering(builder.AddRedis("redis"))
    .WithGrainStorage("Default", blobs);

builder.AddProject<Projects.MySilo>("silo")
    .WithReference(orleans)
    .WithReference(blobs);

builder.Build().Run();

Silo project (Program.cs):

var builder = Host.CreateApplicationBuilder(args);

builder.AddServiceDefaults();
builder.AddKeyedAzureBlobServiceClient("grainstate");
builder.UseOrleans();

builder.Build().Run();

Azure Table Storage with Aspire

AppHost project (Program.cs):

var builder = DistributedApplication.CreateBuilder(args);

var storage = builder.AddAzureStorage("storage");
var tables = storage.AddTables("grainstate");

var orleans = builder.AddOrleans("cluster")
    .WithClustering(builder.AddRedis("redis"))
    .WithGrainStorage("Default", tables);

builder.AddProject<Projects.MySilo>("silo")
    .WithReference(orleans)
    .WithReference(tables);

builder.Build().Run();

Silo project (Program.cs):

var builder = Host.CreateApplicationBuilder(args);

builder.AddServiceDefaults();
builder.AddKeyedAzureTableServiceClient("grainstate");
builder.UseOrleans();

builder.Build().Run();

Tip

During local development, Aspire automatically uses the Azurite emulator for Azure Storage. In production deployments, Aspire connects to your real Azure Storage account based on your Azure deployment configuration.

Important

You must call the appropriate AddKeyed* method (such as AddKeyedAzureBlobServiceClient or AddKeyedAzureTableServiceClient) to register the storage client in the dependency injection container. Orleans providers look up resources by their keyed service name—if you skip this step, Orleans won’t be able to resolve the storage client and will throw a dependency resolution error at runtime.

For comprehensive documentation on Orleans and Aspire integration, see Orleans and Aspire integration.

Applies to: Orleans 3.x

Configure Azure Table Storage

Install the Microsoft.Orleans.Persistence.AzureStorage package from NuGet. The Azure Table Storage provider stores state in a table row, splitting the state across multiple columns if it exceeds the limits of a single column. Each row can hold a maximum of 1 megabyte, as imposed by Azure Table Storage.

Configure the Azure Table Storage grain persistence provider using the AzureTableSiloBuilderExtensions.AddAzureTableGrainStorage extension method.

siloBuilder.AddAzureTableGrainStorage(
    name: "profileStore",
    configureOptions: options =>
    {
        options.ConnectionString =
            "DefaultEndpointsProtocol=https;AccountName=data1;AccountKey=SOMETHING1";
    });

Configure Azure Blob Storage

The Azure Blob Storage provider stores state in a blob.

Configure the Azure Blob Storage grain persistence provider using the AzureBlobSiloBuilderExtensions.AddAzureBlobGrainStorage extension method.

siloBuilder.AddAzureBlobGrainStorage(
    name: "profileStore",
    configureOptions: options =>
    {
        options.ConnectionString =
             "DefaultEndpointsProtocol=https;AccountName=data1;AccountKey=SOMETHING1";
    });