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.
Key packages
You reference one of two mutually exclusive NuGet packages when writing Orleans apps, depending on the chosen workload. For example, when you write an Orleans Silo, you'll reference the Microsoft.Orleans.Server NuGet package. When you write an Orleans Client app, you'll 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-exclusive package, required for Orleans client. |
| Microsoft.Orleans.Sdk | Metapackage required by all Orleans apps, server and client packages depend on this package. |
| Microsoft.Orleans.Server | Server-exclusive package, required for Orleans silos. |
For information on installing NuGet packages, see the following options:
Hosting
| NuGet package | Description |
|---|---|
| Microsoft.Orleans.Hosting.AzureCloudServices | Hosting utilities for Azure Cloud Services of Orleans. |
| 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
| 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. |
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. |
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.Memory | In-memory storage for Orleans. |
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
| 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. |
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
| 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. |
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. |
Tools
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.
Key packages
There are 5 key NuGet packages you will need to use in most scenarios:
Orleans Core Abstractions
Install-Package Microsoft.Orleans.Core.Abstractions
Contains 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
Microsoft.Orleans.OrleansCodeGenerator.Build.
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.
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.
Orleans Server Libraries
Install-Package Microsoft.Orleans.Server
A meta-package for easily building and starting a silo. Includes the following packages:
Microsoft.Orleans.Core.AbstractionsMicrosoft.Orleans.CoreMicrosoft.Orleans.OrleansRuntimeMicrosoft.Orleans.OrleansProviders
Orleans Client Libraries
Install-Package Microsoft.Orleans.Client
A meta-package for easily building and starting an Orleans client (frontend). Includes the following packages:
Microsoft.Orleans.Core.AbstractionsMicrosoft.Orleans.CoreMicrosoft.Orleans.OrleansProviders
Orleans Core Library
Install-Package Microsoft.Orleans.Core
Contains 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
Orleans Runtime
Install-Package Microsoft.Orleans.OrleansRuntime
Library for configuring and starting a silo. Reference it in your silo host project. Included in Microsoft.Orleans.Server meta-package.
Orleans Runtime Abstractions
Install-Package Microsoft.Orleans.Runtime.Abstractions
Contains interfaces and abstractions for types implemented in Microsoft.Orleans.OrleansRuntime.
Orleans Hosting on Azure Cloud Services
Install-Package Microsoft.Orleans.Hosting.AzureCloudServices
Contains helper classes for hosting silos and Orleans clients as Azure Cloud Services (Worker Roles and Web Roles).
Orleans Service Fabric Hosting Support
Install-Package Microsoft.Orleans.Hosting.ServiceFabric
Contains helper classes for hosting silos as a stateless Service Fabric service.
Clustering providers
The below packages include plugins for persisting cluster membership data in various storage technologies.
Orleans clustering provider for Azure Table Storages
Install-Package Microsoft.Orleans.Clustering.AzureStorage
Includes the plugin for using Azure Tables for storing cluster membership data.
Orleans clustering provider for ADO.NET Providers
Install-Package Microsoft.Orleans.Clustering.AdoNet
Includes the plugin for using ADO.NET for storing cluster membership data in one of the supported databases.
Orleans Consul Utilities
Install-Package Microsoft.Orleans.OrleansConsulUtils
Includes the plugin for using Consul for storing cluster membership data.
Orleans ZooKeeper Utilities
Install-Package Microsoft.Orleans.OrleansZooKeeperUtils
Includes the plugin for using ZooKeeper for storing cluster membership data.
Orleans clustering provider for AWS DynamoDB
Install-Package Microsoft.Orleans.Clustering.DynamoDB
Includes the plugin for using AWS DynamoDB for storing cluster membership data.
Reminder providers
The below packages include plugins for persisting reminders in various storage technologies.
Orleans Reminders Azure Table Storage
Install-Package Microsoft.Orleans.Reminders.AzureStorage
Includes the plugin for using Azure Tables for storing reminders.
Orleans Reminders ADO.NET Providers
Install-Package Microsoft.Orleans.Reminders.AdoNet
Includes the plugin for using ADO.NET for storing reminders in one of the supported databases.
Orleans reminders provider for AWS DynamoDB
Install-Package Microsoft.Orleans.Reminders.DynamoDB
Includes the plugin for using AWS DynamoDB for storing reminders.
Grain storage providers
The below packages include plugins for persisting grain state in various storage technologies.
Orleans Persistence Azure Storage
Install-Package Microsoft.Orleans.Persistence.AzureStorage
Includes the plugins for using Azure Tables or Azure Blobs for storing grain state.
Orleans Persistence ADO.NET Providers
Install-Package Microsoft.Orleans.Persistence.AdoNet
Includes the plugin for using ADO.NET for storing grain state in one of the supported databases.
Orleans Persistence DynamoDB
Install-Package Microsoft.Orleans.Persistence.DynamoDB
Includes the plugin for using AWS DynamoDB for storing grain state.
Stream providers
The below packages include plugins for delivering streaming events.
Orleans ServiceBus Utilities
Install-Package Microsoft.Orleans.OrleansServiceBus
Includes the stream provider for Azure Event Hubs.
Orleans Streaming Azure Storage
Install-Package Microsoft.Orleans.Streaming.AzureStorage
Includes the stream provider for Azure Queues.
Orleans Streaming AWS SQS
Install-Package Microsoft.Orleans.Streaming.SQS
Includes the stream provider for AWS SQS service.
Orleans Google Cloud Platform Utilities
Install-Package Microsoft.Orleans.OrleansGCPUtils
Includes the stream provider for GCP PubSub service.
Additional packages
Orleans Code Generation
Install-Package Microsoft.Orleans.OrleansCodeGenerator
Includes the run-time code generator.
Orleans Event-Sourcing
Install-Package Microsoft.Orleans.EventSourcing
Contains a set of base types for creating grain classes with event-sourced state.
Development and testing
Orleans Providers
Install-Package Microsoft.Orleans.OrleansProviders
Contains 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.
Orleans Testing Host Library
Install-Package Microsoft.Orleans.TestingHost
Includes the library for hosting silos and clients in a testing project.
Serializers
Orleans Bond Serializer
Install-Package Microsoft.Orleans.Serialization.Bond
Includes support for Bond serializer.
Orleans Google Utilities
Install-Package Microsoft.Orleans.OrleansGoogleUtils
Includes Google Protocol Buffers serializer.
Orleans protobuf-net Serializer
Install-Package Microsoft.Orleans.ProtobufNet
Includes protobuf-net version of Protocol Buffers serializer.
Telemetry
Orleans Telemetry Consumer - Performance Counters
Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.Counters
Windows Performance Counters implementation of Orleans Telemetry API.
Orleans Telemetry Consumer - Azure Application Insights
Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.AI
Includes the telemetry consumer for Azure Application Insights.
Orleans Telemetry Consumer - NewRelic
Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.NewRelic
Includes the telemetry consumer for NewRelic.
Transactions
Orleans Transactions support
Install-Package Microsoft.Orleans.Transactions
Includes support for cross-grain transactions (beta).
Orleans Transactions on Azure
Install-Package Microsoft.Orleans.Transactions.AzureStorage
Includes a plugin for persisting transaction log in Azure Table (beta).
Tools
Orleans Performance Counter Tool
Install-Package Microsoft.Orleans.CounterControl
Includes 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.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for