Orleans NuGet packages
Consumers of Orleans rely on various NuGet packages to achieve specific desired behaviors. There are several common packages and abstractions, and many individual single purpose packages. This article provides insights to help developers learn which Orleans packages should be used.
Applies to: Orleans 7.0, Orleans 8.0, Orleans 9.0, Orleans 10.0
Key packages
Section titled “Key packages”Orleans provides several NuGet packages for different scenarios. When building an Orleans silo (server), reference the Microsoft.Orleans.Server NuGet package. The Server package includes everything from the Client package, so silo projects can also act as clients without additional references. When building a standalone client application that connects to an Orleans cluster but doesn’t host a silo, reference the Microsoft.Orleans.Client NuGet package. All Orleans projects, such as abstractions or grain class libraries, reference the Microsoft.Orleans.Sdk NuGet package. The Microsoft.Orleans.Sdk package is included with both the Client and Server packages.
| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Client | Client library for connecting to Orleans clusters. |
| Microsoft.Orleans.Sdk | Metapackage for grain development, included in both Client and Server packages. |
| Microsoft.Orleans.Server | Server library for hosting Orleans silos. |
For information on installing NuGet packages, see the following options:
Applies to: Orleans 10.0
Orleans Dashboard
Section titled “Orleans Dashboard”The official Orleans Dashboard provides real-time cluster monitoring and visualization.
| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Dashboard | Orleans Dashboard for real-time cluster monitoring and visualization. |
| Microsoft.Orleans.Dashboard.Abstractions | Abstractions for Orleans Dashboard. |
Applies to: Orleans 9.0, Orleans 8.0, Orleans 7.0
One popular Orleans tool is the OrleansDashboard NuGet package. This dashboard provides some simple metrics and insights into what is happening inside your Orleans app. For more information, see GitHub: Orleans Dashboard.
Applies to: Orleans 7.0, Orleans 8.0, Orleans 9.0, Orleans 10.0
Hosting
Section titled “Hosting”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Hosting.Kubernetes | Orleans hosting support for Kubernetes. |
| Microsoft.Orleans.Runtime | Core runtime library of Orleans that hosts and executes grains within a silo. |
Clustering providers
Section titled “Clustering providers”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Clustering.AzureStorage | Orleans clustering provider backed by Azure Table Storage. |
| Microsoft.Orleans.Clustering.AdoNet | Orleans clustering provider backed by ADO.NET. |
| Microsoft.Orleans.Clustering.DynamoDB | Orleans clustering provider backed by AWS DynamoDB. |
| Microsoft.Orleans.Clustering.Cosmos | Orleans clustering provider backed by Azure Cosmos DB. |
| Microsoft.Orleans.Clustering.Redis | Orleans clustering provider backed by Redis. |
| Microsoft.Orleans.Clustering.Cassandra | Orleans clustering provider backed by Apache Cassandra. |
| Microsoft.Orleans.Clustering.Consul | Orleans clustering provider backed by HashiCorp Consul. |
| Microsoft.Orleans.Clustering.ZooKeeper | Orleans clustering provider backed by Apache ZooKeeper. |
Reminder providers
Section titled “Reminder providers”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Reminders | Reminders library for Microsoft Orleans used on the server. |
| Microsoft.Orleans.Reminders.AzureStorage | Orleans reminders provider backed by Azure Table Storage. |
| Microsoft.Orleans.Reminders.AdoNet | Orleans reminders provider backed by ADO.NET. |
| Microsoft.Orleans.Reminders.DynamoDB | Orleans reminders provider backed by AWS DynamoDB. |
| Microsoft.Orleans.Reminders.Cosmos | Orleans reminders provider backed by Azure Cosmos DB. |
| Microsoft.Orleans.Reminders.Redis | Orleans reminders provider backed by Redis. |
Grain storage providers
Section titled “Grain storage providers”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Persistence.AdoNet | Orleans persistence provider backed by ADO.NET. |
| Microsoft.Orleans.Persistence.AzureStorage | Orleans persistence provider backed by Azure Table Storage. |
| Microsoft.Orleans.Persistence.DynamoDB | Orleans persistence provider backed by AWS DynamoDB. |
| Microsoft.Orleans.Persistence.Cosmos | Orleans persistence provider backed by Azure Cosmos DB. |
| Microsoft.Orleans.Persistence.Redis | Orleans persistence provider backed by Redis. |
| Microsoft.Orleans.Persistence.Memory | In-memory storage for Orleans. |
Grain directory providers
Section titled “Grain directory providers”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.GrainDirectory.AzureStorage | Orleans grain directory provider backed by Azure Table Storage. |
| Microsoft.Orleans.GrainDirectory.AdoNet | Orleans grain directory provider backed by ADO.NET. |
| Microsoft.Orleans.GrainDirectory.Redis | Orleans grain directory provider backed by Redis. |
Stream providers
Section titled “Stream providers”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Streaming | Streaming library for Orleans used both on the client and server. |
| Microsoft.Orleans.Streaming.AzureStorage | Orleans streaming provider backed by Azure Queue Storage. |
| Microsoft.Orleans.Streaming.EventHubs | Orleans streaming provider backed by Azure Event Hubs. |
| Microsoft.Orleans.Streaming.SQS | Orleans streaming provider backed by AWS SQS. |
Additional packages
Section titled “Additional packages”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Analyzers | C# Analyzers for Orleans. |
| Microsoft.Orleans.CodeGenerator | Code generation library for Microsoft.Orleans.Serialization. |
| Microsoft.Orleans.EventSourcing | Base types for creating Orleans grains with event-sourced state. |
| Microsoft.Orleans.Connections.Security | Support for security communication using TLS in Orleans. |
| Microsoft.Orleans.BroadcastChannel | Support for broadcast channels in Orleans. |
Development and testing
Section titled “Development and testing”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.TestingHost | Orleans library for hosting a silo in a testing project. |
| Microsoft.Orleans.Transactions.TestKit.Base | Test kit base library for transactions. |
| Microsoft.Orleans.Transactions.TestKit.xUnit | xUnit test kit library for transactions. |
| Microsoft.Orleans.Serialization.TestKit | Test kit for projects using Microsoft.Orleans.Serialization. |
Serializers
Section titled “Serializers”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Serialization | Fast, flexible, and version-tolerant serializer for .NET. |
| Microsoft.Orleans.Serialization.Abstractions | Serialization abstractions for Orleans. |
| Microsoft.Orleans.Serialization.SystemTextJson | System.Text.Json integration for Microsoft.Orleans.Serialization. |
| Microsoft.Orleans.Serialization.FSharp | F# core type support for Microsoft.Orleans.Serialization. |
| Microsoft.Orleans.Serialization.NewtonsoftJson | Newtonsoft.Json integration for Microsoft.Orleans.Serialization. |
| Microsoft.Orleans.Serialization.MessagePack | MessagePack integration for Microsoft.Orleans.Serialization. |
| Microsoft.Orleans.Serialization.Protobuf | Protocol Buffers (Protobuf) integration for Microsoft.Orleans.Serialization. |
Transactions
Section titled “Transactions”| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Transactions | Core transaction library of Orleans used on the server. |
| Microsoft.Orleans.Transactions.AzureStorage | Orleans transactions storage provider backed by Azure Storage. |
Applies to: Orleans 3.x
Key packages
Section titled “Key packages”There are 5 key NuGet packages you will need to use in most scenarios:
Install-Package Microsoft.Orleans.Core.AbstractionsContains Orleans.Core.Abstractions.dll, which defines Orleans public types that are needed for developing application code (grain interfaces and classes). This package is needed to be directly or indirectly referenced by any Orleans project. Add it to your projects that define grain interfaces and classes.
Orleans build-time code generation
Section titled “Orleans build-time code generation”-
Microsoft.Orleans.OrleansCodeGenerator.Build.
Terminal window Install-Package Microsoft.Orleans.OrleansCodeGenerator.BuildAppeared in Orleans 1.2.0. Build time support for grain interfaces and implementation projects. Add it to your grain interfaces and implementation projects to enable code generation of grain references and serializers.
-
Microsoft.Orleans.CodeGenerator.MSBuild.
Terminal window Install-Package Microsoft.Orleans.CodeGenerator.MSBuildAppeared as part of Orleans 2.1.0. An alternative to the
Microsoft.Orleans.OrleansCodeGenerator.Buildpackage. Leverages Roslyn for code analysis to avoid loading application binaries and improves support for incremental builds, which should result in shorter build times.
Install-Package Microsoft.Orleans.ServerA meta-package for easily building and starting a silo. Includes the following packages:
Microsoft.Orleans.Core.AbstractionsMicrosoft.Orleans.CoreMicrosoft.Orleans.OrleansRuntimeMicrosoft.Orleans.OrleansProviders
Install-Package Microsoft.Orleans.ClientA meta-package for easily building and starting an Orleans client (frontend). Includes the following packages:
Microsoft.Orleans.Core.AbstractionsMicrosoft.Orleans.CoreMicrosoft.Orleans.OrleansProviders
Install-Package Microsoft.Orleans.CoreContains implementation for most Orleans public types used by application code and Orleans clients (frontends). Reference it for building libraries and client applications that use Orleans types but don’t deal with hosting or silos. Included in Microsoft.Orleans.Client and Microsoft.Orleans.Server meta-packages, and is referenced, directly or indirectly, by most other packages.
Hosting
Section titled “Hosting”Install-Package Microsoft.Orleans.OrleansRuntimeLibrary for configuring and starting a silo. Reference it in your silo host project. Included in Microsoft.Orleans.Server meta-package.
Install-Package Microsoft.Orleans.Runtime.AbstractionsContains interfaces and abstractions for types implemented in Microsoft.Orleans.OrleansRuntime.
Install-Package Microsoft.Orleans.Hosting.AzureCloudServicesContains helper classes for hosting silos and Orleans clients as Azure Cloud Services (Worker Roles and Web Roles).
Install-Package Microsoft.Orleans.Hosting.ServiceFabricContains helper classes for hosting silos as a stateless Service Fabric service.
Clustering providers
Section titled “Clustering providers”The below packages include plugins for persisting cluster membership data in various storage technologies.
Orleans clustering provider for Azure Table Storages
Section titled “Orleans clustering provider for Azure Table Storages”Install-Package Microsoft.Orleans.Clustering.AzureStorageIncludes the plugin for using Azure Tables for storing cluster membership data.
Orleans clustering provider for ADO.NET Providers
Section titled “Orleans clustering provider for ADO.NET Providers”Install-Package Microsoft.Orleans.Clustering.AdoNetIncludes the plugin for using ADO.NET for storing cluster membership data in one of the supported databases.
Install-Package Microsoft.Orleans.OrleansConsulUtilsIncludes the plugin for using Consul for storing cluster membership data.
Install-Package Microsoft.Orleans.OrleansZooKeeperUtilsIncludes the plugin for using ZooKeeper for storing cluster membership data.
Orleans clustering provider for AWS DynamoDB
Section titled “Orleans clustering provider for AWS DynamoDB”Install-Package Microsoft.Orleans.Clustering.DynamoDBIncludes the plugin for using AWS DynamoDB for storing cluster membership data.
Reminder providers
Section titled “Reminder providers”The below packages include plugins for persisting reminders in various storage technologies.
Install-Package Microsoft.Orleans.Reminders.AzureStorageIncludes the plugin for using Azure Tables for storing reminders.
Install-Package Microsoft.Orleans.Reminders.AdoNetIncludes the plugin for using ADO.NET for storing reminders in one of the supported databases.
Orleans reminders provider for AWS DynamoDB
Section titled “Orleans reminders provider for AWS DynamoDB”Install-Package Microsoft.Orleans.Reminders.DynamoDBIncludes the plugin for using AWS DynamoDB for storing reminders.
Grain storage providers
Section titled “Grain storage providers”The below packages include plugins for persisting grain state in various storage technologies.
Install-Package Microsoft.Orleans.Persistence.AzureStorageIncludes the plugins for using Azure Tables or Azure Blobs for storing grain state.
Install-Package Microsoft.Orleans.Persistence.AdoNetIncludes the plugin for using ADO.NET for storing grain state in one of the supported databases.
Install-Package Microsoft.Orleans.Persistence.DynamoDBIncludes the plugin for using AWS DynamoDB for storing grain state.
Stream providers
Section titled “Stream providers”The below packages include plugins for delivering streaming events.
Install-Package Microsoft.Orleans.OrleansServiceBusIncludes the stream provider for Azure Event Hubs.
Install-Package Microsoft.Orleans.Streaming.AzureStorageIncludes the stream provider for Azure Queues.
Install-Package Microsoft.Orleans.Streaming.SQSIncludes the stream provider for AWS SQS service.
Install-Package Microsoft.Orleans.OrleansGCPUtilsIncludes the stream provider for GCP PubSub service.
Additional packages
Section titled “Additional packages”Install-Package Microsoft.Orleans.OrleansCodeGeneratorIncludes the run-time code generator.
Install-Package Microsoft.Orleans.EventSourcingContains a set of base types for creating grain classes with event-sourced state.
Development and testing
Section titled “Development and testing”Install-Package Microsoft.Orleans.OrleansProvidersContains a set of persistence and stream providers that keep data in memory. Intended for testing. In general, not recommended for production use, unless data loss in case of a silo failure is acceptable.
Install-Package Microsoft.Orleans.TestingHostIncludes the library for hosting silos and clients in a testing project.
Serializers
Section titled “Serializers”Install-Package Microsoft.Orleans.Serialization.BondIncludes support for Bond serializer.
Install-Package Microsoft.Orleans.OrleansGoogleUtilsIncludes Google Protocol Buffers serializer.
Install-Package Microsoft.Orleans.ProtobufNetIncludes protobuf-net version of Protocol Buffers serializer.
Telemetry
Section titled “Telemetry”Orleans Telemetry Consumer - Performance Counters
Section titled “Orleans Telemetry Consumer - Performance Counters”Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.CountersWindows Performance Counters implementation of Orleans Telemetry API.
Orleans Telemetry Consumer - Azure Application Insights
Section titled “Orleans Telemetry Consumer - Azure Application Insights”Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.AIIncludes the telemetry consumer for Azure Application Insights.
Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.NewRelicIncludes the telemetry consumer for NewRelic.
Transactions
Section titled “Transactions”Install-Package Microsoft.Orleans.TransactionsIncludes support for cross-grain transactions (beta).
Install-Package Microsoft.Orleans.Transactions.AzureStorageIncludes a plugin for persisting transaction log in Azure Table (beta).
Install-Package Microsoft.Orleans.CounterControlIncludes OrleansCounterControl.exe, which registers Windows performance counter categories for Orleans statistics and for deployed grain classes. Requires elevation. Can be executed in Azure as part of a role startup task.