Orleans.Persistence.CosmosDB 3.0.0

.NET Standard 2.0
There is a newer version of this package available.
See the version list below for details.
dotnet add package Orleans.Persistence.CosmosDB --version 3.0.0
NuGet\Install-Package Orleans.Persistence.CosmosDB -Version 3.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Orleans.Persistence.CosmosDB" Version="3.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Orleans.Persistence.CosmosDB --version 3.0.0
#r "nuget: Orleans.Persistence.CosmosDB, 3.0.0"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Orleans.Persistence.CosmosDB as a Cake Addin
#addin nuget:?package=Orleans.Persistence.CosmosDB&version=3.0.0

// Install Orleans.Persistence.CosmosDB as a Cake Tool
#tool nuget:?package=Orleans.Persistence.CosmosDB&version=3.0.0


It is not mandatory to use all the providers at once. Just pick the one you are interested in from the samples and you should be good as they don't depend on each other.



var silo = new SiloHostBuilder()
    .UseCosmosDBMembership(opt => 
        // Use CosmosDB as the cluster membership table.
        // Configure CosmosDB settings in opt.
    .AddCosmosDBGrainStorageAsDefault(opt => 
        // Configure CosmosDB persistence provider.
        // Configure CosmosDB settings in opt.
    .UseCosmosDBReminderService(op => 
        // Configure CosmosDB reminders provider.
        // Configure CosmosDB settings in opt.
await silo.StartAsync();



var clientConfig = new ClientConfiguration();

var client = new ClientBuilder()
    .UseCosmosDBGatewayListProvider(opt => 
        // Use CosmosDB as the Gateway list provider.
        // Configure CosmosDB settings in opt.
    await client.Connect();

Great! Now you have Orleans configured to use Azure CosmosDB as the back storage for its providers!

Custom partition keys for storage provider

By default the grain type is used as partition key, however this limits the storage size for a single grain type as a single logical partition has an upper limit of 10 GB storage.

It is possible to override the default by implementing a custom IPartitionKeyProvider. The custom implementation of IPartitionKeyProvider can be registered by using the dependency injection usual methods like:

services.AddSingleton<IPartitionKeyProvider, MyCustomPKProvider>();

There is also some overloads of AddCosmosDBGrainStorage and AddCosmosDBGrainStorageAsDefault that allow you to pass the IPartitionKeyProvider implementation.

If no IPartitionKeyProvider is used, the default one will be uses which use full name of the grain type will be used as partition key.


public class PrimaryKeyPartitionKeyProvider : IPartitionKeyProvider
    public ValueTask<string> GetPartitionKey(string grainType, GrainReference grainReference) 
        return new ValueTask<string>(grainReference.GetPrimaryKey().ToString());

The example above use the Primary key as partition key.

In order to prevent cross partition queries the partition key must be available to the client upon reading data, hence the delegate input is limited to the graintype and grainreference. The grain reference contains the grain id, with combination, and a type identifier.

For further details on partitioning in CosmosDB see https://docs.microsoft.com/en-us/azure/cosmos-db/partitioning-overview.

Backwards compatibility

The change will not affect existing systems. Configuring custom partition key builders for an existing system will throw a BadGrainStorageConfigException stating incompatibility. To start using custom partition key builders the old documents must be updated with a /PartitionKey property where the value is set using the same functionality as the Func<GrainReference, string> delegate specified in options. Once all documents are updated, the data must be migrated to a new CosmosDB collection using Azure Data Factory, CosmosDB Migration tool or custom code.


The current indexing fork relies on CosmosDB stored procedures for lookup. As stored procedures must be executed against a specific partition, the use of custom partition key builders is not compatible with the Orleans indexing fork.


PRs and feedback are very welcome!

Product Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Orleans.Persistence.CosmosDB:

Package Downloads

This library provides primitives to set up a configurable, application-agnostic Orleans silo and clients. Use it with the Orleans.Contrib.UniversalSilo.Templates to get started with Orleans.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
3.0.3 29,226 4/24/2020
3.0.2 4,839 3/23/2020
3.0.1 1,413 1/29/2020
3.0.0 523 11/14/2019
1.3.0 2,208 4/3/2019
1.2.1 1,225 3/20/2019
1.2.0 604 3/19/2019
1.1.42 1,691 9/28/2018
1.1.40 1,204 3/28/2018
1.1.38 882 3/28/2018
1.1.0-rc2-36 687 3/13/2018
1.1.0-rc1-34 719 3/12/2018
1.1.0-rc1-29 653 2/27/2018
1.0.1-preview-27 727 2/10/2018
1.0.1-preview-25 758 2/5/2018
1.0.1-preview-21 605 2/1/2018
1.0.1-preview-19 713 2/1/2018
1.0.0-preview-17 612 2/1/2018
1.0.0-preview-16 715 2/1/2018
1.0.0-preview-1 898 2/1/2018