Amazon DynamoDB grain persistence

Install the Microsoft.Orleans.Persistence.DynamoDB package and configure a named provider with AddDynamoDBGrainStorage:

siloBuilder.AddDynamoDBGrainStorage(
    "profileStore",
    options =>
    {
        options.Service = "us-west-2";
        options.ServiceId = "my-application";
        options.TableName = "OrleansGrainState";
        options.CreateIfNotExists = false;
    });

The AWS SDK for .NET credential and profile resolution chain supplies credentials when AccessKey and SecretKey aren’t set. In production, prefer workload credentials such as an IAM role over long-lived keys. ProfileName, AccessKey, SecretKey, and Token are available when the deployment environment requires explicit SDK configuration. See the AWS CLI configuration-file reference for profile configuration.

Capacity and lifecycle

UseProvisionedThroughput selects provisioned-capacity behavior. When enabled, configure ReadCapacityUnits and WriteCapacityUnits. CreateIfNotExists and UpdateIfExists allow provider-managed table changes, but infrastructure-managed provisioning is usually preferable in production.

DeleteStateOnClear controls whether clearing state deletes the item or resets it. TimeToLive advances the item’s expiration on every write; enable it only when disappearing state is valid application behavior.

Service identity and upgrades

ServiceId prefixes the key of every grain state as {ServiceId}_{grainId}. Configure it explicitly for each DynamoDB grain storage provider and keep it stable across deployments that share the same logical application state. Startup validation reports an OrleansConfigurationException when the value is unset.

For a new deployment, choose a stable application identifier, such as ServiceId. When upgrading an existing deployment, retain the value used to write its state. If the deployment used the previous empty-string default, explicitly set ServiceId to string.Empty in code or "" in configuration to keep reading and writing the same keys. Choosing a different value selects a different state namespace; accessing existing state under that prefix requires a separate data migration.

The provider uses optimistic concurrency and rejects stale writes.

Serialization

Set GrainStorageSerializer to customize the stored representation. Changing serializers doesn’t rewrite existing items, so the replacement must read the previous representation or be accompanied by a migration.