Edit

Share via

Orleans NuGet packages

  • Article

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.Build

    Appeared 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.MSBuild

    Appeared as part of Orleans 2.1.0. An alternative to the Microsoft.Orleans.OrleansCodeGenerator.Build package. 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.Abstractions
  • Microsoft.Orleans.Core
  • Microsoft.Orleans.OrleansRuntime
  • Microsoft.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.Abstractions
  • Microsoft.Orleans.Core
  • Microsoft.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.