Microsoft Orleans

https://learn.microsoft.com/en-us/dotnet/orleans/
Admin
Microsoft Orleans is an SDK for building distributed, cloud-native .NET applications using the actor...
Tokens:260,989
Snippets:2,285
Trust Score:10
Update:3 days ago
Show doc for...
Tokens:
Raw
### Start a local silo with custom configuration

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/local-development-configuration

Example showing how to build and start a local silo, configuring ClusterOptions and EndpointOptions to listen on the loopback address.

```csharp
public static async Task StartLocalSilo()
{
    try
    {
        var host = await BuildAndStartSiloAsync();

        Console.WriteLine("Press Enter to terminate...");
        Console.ReadLine();

        await host.StopAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine(ex);
    }
}

static async Task<IHost> BuildAndStartSiloAsync()
{
    var host = new HostBuilder()
      .UseOrleans(builder =>
      {
          builder.UseLocalhostClustering()
              .Configure<ClusterOptions>(options =>
              {
                  options.ClusterId = "dev";
                  options.ServiceId = "MyAwesomeService";
              })
              .Configure<EndpointOptions>(
                  options => options.AdvertisedIPAddress = IPAddress.Loopback)
              .ConfigureLogging(logging => logging.AddConsole());
      })
      .Build();

    await host.StartAsync();

    return host;
}
```

--------------------------------

### Install Microsoft.Orleans.Server

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the meta-package for building and starting an Orleans silo.

```PowerShell
Install-Package Microsoft.Orleans.Server
```

--------------------------------

### Install Microsoft.Orleans.OrleansGoogleUtils

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the Google Protocol Buffers serializer.

```PowerShell
Install-Package Microsoft.Orleans.OrleansGoogleUtils
```

--------------------------------

### Install Microsoft.Orleans.Streaming.AzureStorage

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the stream provider for Azure Queues.

```PowerShell
Install-Package Microsoft.Orleans.Streaming.AzureStorage
```

--------------------------------

### Install Microsoft.Orleans.OrleansGCPUtils

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the stream provider for GCP PubSub service.

```PowerShell
Install-Package Microsoft.Orleans.OrleansGCPUtils
```

--------------------------------

### Install Microsoft.Orleans.ProtobufNet

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the protobuf-net version of the Protocol Buffers serializer.

```PowerShell
Install-Package Microsoft.Orleans.ProtobufNet
```

--------------------------------

### Install Microsoft.Orleans.OrleansRuntime

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the library for configuring and starting a silo. This package is included in the Microsoft.Orleans.Server meta-package.

```PowerShell
Install-Package Microsoft.Orleans.OrleansRuntime
```

--------------------------------

### Install Microsoft.Orleans.OrleansTelemetryConsumers.NewRelic

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the telemetry consumer for NewRelic.

```PowerShell
Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.NewRelic
```

--------------------------------

### Install Microsoft.Orleans.OrleansServiceBus

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the stream provider for Azure Event Hubs.

```PowerShell
Install-Package Microsoft.Orleans.OrleansServiceBus
```

--------------------------------

### Install Microsoft.Orleans.Serialization.Bond

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs support for the Bond serializer.

```PowerShell
Install-Package Microsoft.Orleans.Serialization.Bond
```

--------------------------------

### Install Microsoft.Orleans.Runtime.Abstractions

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs interfaces and abstractions for types implemented in Microsoft.Orleans.OrleansRuntime.

```PowerShell
Install-Package Microsoft.Orleans.Runtime.Abstractions
```

--------------------------------

### Install Microsoft.Orleans.TestingHost

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the library used for hosting silos and clients within a testing project.

```PowerShell
Install-Package Microsoft.Orleans.TestingHost
```

--------------------------------

### Install Microsoft.Orleans.Streaming.SQS

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the stream provider for AWS SQS service.

```PowerShell
Install-Package Microsoft.Orleans.Streaming.SQS
```

--------------------------------

### Install Aspire.Hosting.Kubernetes NuGet package

Source: https://learn.microsoft.com/en-us/dotnet/orleans/deployment/kubernetes

Installs the Aspire Kubernetes hosting integration package into the AppHost project.

```bash
dotnet add package Aspire.Hosting.Kubernetes

```

--------------------------------

### Install Microsoft.Orleans.Hosting.ServiceFabric

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs helper classes for hosting silos as a stateless Service Fabric service.

```PowerShell
Install-Package Microsoft.Orleans.Hosting.ServiceFabric
```

--------------------------------

### Install Microsoft.Orleans.Reminders.AzureStorage

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the plugin for using Azure Tables for storing reminders.

```PowerShell
Install-Package Microsoft.Orleans.Reminders.AzureStorage
```

--------------------------------

### Install Microsoft.Orleans.Persistence.AzureStorage

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the plugins for using Azure Tables or Azure Blobs for storing grain state.

```PowerShell
Install-Package Microsoft.Orleans.Persistence.AzureStorage
```

--------------------------------

### Install Microsoft.Orleans.OrleansConsulUtils

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the plugin for using Consul for storing cluster membership data.

```PowerShell
Install-Package Microsoft.Orleans.OrleansConsulUtils
```

--------------------------------

### Install Microsoft.Orleans.Persistence.AdoNet package

Source: https://learn.microsoft.com/en-us/dotnet/orleans/grains/grain-persistence/relational-storage

Install the base package required to enable ADO.NET grain storage functionality.

```powershell
Install-Package Microsoft.Orleans.Persistence.AdoNet
```

--------------------------------

### Install Microsoft.Orleans.Client NuGet Package

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/local-development-configuration

Command to install the Microsoft.Orleans.Client meta-package required for client development.

```powershell
Install-Package Microsoft.Orleans.Client
```

--------------------------------

### Install Microsoft.Orleans.Reminders.AdoNet

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the plugin for using ADO.NET for storing reminders in supported databases.

```PowerShell
Install-Package Microsoft.Orleans.Reminders.AdoNet
```

--------------------------------

### Install Microsoft.Orleans.Persistence.DynamoDB

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the plugin for using AWS DynamoDB for storing grain state.

```PowerShell
Install-Package Microsoft.Orleans.Persistence.DynamoDB
```

--------------------------------

### Install Microsoft.Orleans.Clustering.AdoNet

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the plugin for using ADO.NET for storing cluster membership data in supported databases.

```PowerShell
Install-Package Microsoft.Orleans.Clustering.AdoNet
```

--------------------------------

### Install Microsoft.Orleans.Core

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the core library containing implementations for public types used by application code and clients.

```PowerShell
Install-Package Microsoft.Orleans.Core
```

--------------------------------

### Setup stream provider and stream handle

Source: https://learn.microsoft.com/en-us/dotnet/orleans/streaming/streams-programming-apis

Demonstrates how to retrieve a stream provider and obtain a handle to a specific stream within a grain.

```C#
public async Task SetupStream()
{
    IStreamProvider streamProvider = this.GetStreamProvider("SimpleStreamProvider");
    StreamId streamId = StreamId.Create("MyStreamNamespace", this.GetPrimaryKey());
    IAsyncStream<string> stream = streamProvider.GetStream<string>(streamId);
}
```

--------------------------------

### Get stream handle with GUID and namespace

Source: https://learn.microsoft.com/en-us/dotnet/orleans/streaming/streams-programming-apis

Shows an alternative way to retrieve a stream handle using a GUID and a namespace string.

```C#
IStreamProvider streamProvider = base.GetStreamProvider("SimpleStreamProvider");
IAsyncStream<T> stream = streamProvider.GetStream<T>(Guid, "MyStreamNamespace");
```

--------------------------------

### Configure and run a silo with Host.CreateDefaultBuilder

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/local-development-configuration

Example Program.cs file demonstrating how to configure a silo using the Microsoft.Extensions.Hosting package and UseLocalhostClustering.

```csharp
using Microsoft.Extensions.Hosting;

await Host.CreateDefaultBuilder(args)
    .UseOrleans(siloBuilder =>
    {
        siloBuilder.UseLocalhostClustering();
    })
    .RunConsoleAsync();
```

--------------------------------

### GetStreamProvider and GetStream (alternative)

Source: https://learn.microsoft.com/en-us/dotnet/orleans/streaming/streams-programming-apis

Alternative way to get a stream provider and stream handle using a GUID and namespace.

```APIDOC
## GetStreamProvider and GetStream (alternative)

### Description
Alternative method to get a stream provider and obtain a stream handle using a GUID and a stream namespace.

### Method
GetStreamProvider and GetStream (local calls)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Method Parameters
- **providerName** (string) - Required - The name of the stream provider.
- **guid** (Guid) - Required - The GUID part of the stream identity.
- **streamNamespace** (string) - Optional - The stream namespace, can be null.

### Request Example
```csharp
IStreamProvider streamProvider = base.GetStreamProvider("SimpleStreamProvider");
IAsyncStream<T> stream = streamProvider.GetStream<T>(Guid, "MyStreamNamespace");
```

### Response
#### Success Response
- **stream** (IAsyncStream<T>) - The stream handle.

#### Response Example
```csharp
IAsyncStream<T> stream = streamProvider.GetStream<T>(Guid, "MyStreamNamespace");
```
```

--------------------------------

### Main Bicep entry point file (main.bicep)

Source: https://learn.microsoft.com/en-us/dotnet/orleans/deployment/deploy-to-azure-app-service

The main.bicep file serves as the entry point for deployment, defining parameters, modules for storage and logs, and the virtual network configuration.

```Bicep
param appName string
param location string = resourceGroup().location

module storageModule 'storage.bicep' = {
  name: 'orleansStorageModule'
  params: {
    name: '${appName}storage'
    location: location
  }
}

module logsModule 'logs-and-insights.bicep' = {
  name: 'orleansLogModule'
  params: {
    operationalInsightsName: '${appName}-logs'
    appInsightsName: '${appName}-insights'
    location: location
  }
}

resource vnet 'Microsoft.Network/virtualNetworks@2021-05-01' = {
  name: '${appName}-vnet'
  location: location
  properties: {
    addressSpace: {
      addressPrefixes: [
        '172.17.0.0/16',
        '192.168.0.0/16'
      ]
    }
    subnets: [
      {
        name: 'default'
        properties: {
          addressPrefix: '172.17.0.0/24'
          delegations: [
            {
              name: 'delegation'
              properties: {
                serviceName: 'Microsoft.Web/serverFarms'
              }
            }
          ]
        }
      }
      {
        name: 'staging'
        properties: {
          addressPrefix: '192.168.0.0/24'
          delegations: [
            {
              name: 'delegation'
              properties: {
                serviceName: 'Microsoft.Web/serverFarms'
              }
            }
          ]
        }
      }
    ]
  }
}

module siloModule 'app-service.bicep' = {
  name: 'orleansSiloModule'
  params: {
    appName: appName
    location: location
    vnetSubnetId: vnet.properties.subnets[0].id
    stagingSubnetId: vnet.properties.subnets[1].id
    appInsightsConnectionString: logsModule.outputs.appInsightsConnectionString
    appInsightsInstrumentationKey: logsModule.outputs.appInsightsInstrumentationKey
    storageConnectionString: storageModule.outputs.connectionString
  }
}
```

--------------------------------

### Subscribe to a stream in OnActivateAsync

Source: https://learn.microsoft.com/en-us/dotnet/orleans/streaming/streams-programming-apis

This example demonstrates how to get a stream provider and subscribe to a stream within the grain's activation lifecycle.

```C#
public override async Task OnActivateAsync()
{
    var streamProvider = this.GetStreamProvider(PROVIDER_NAME);
    var stream =
        streamProvider.GetStream<string>(
            this.GetPrimaryKey(), "MyStreamNamespace");

    await stream.SubscribeAsync(OnNextAsync);
}
```

--------------------------------

### DoClientWork method to call grain

Source: https://learn.microsoft.com/en-us/dotnet/orleans/tutorials-and-samples/overview-helloworld

Client-side method that gets a reference to the IHello grain with key 0, calls SayHello with a greeting, and prints the response. This method is called after starting the client with StartClientWithRetries().

```C#
static async Task DoClientWork(IClusterClient client)
{
    var friend = client.GetGrain<IHello>(0);
    var response = await friend.SayHello("Good morning, my friend!");
    Console.WriteLine($"\n\n{response}\n\n");
}

```

--------------------------------

### Define member IDs in a type hierarchy

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/serialization

Use the [Id(0)] attribute to start member IDs at zero for each type. IDs in a subclass and its base class can safely overlap as shown in this example.

```csharp
[GenerateSerializer]
public class MyBaseClass
{
    [Id(0)]
    public int MyBaseInt { get; set; }
}

[GenerateSerializer]
public sealed class MySubClass : MyBaseClass
{
    [Id(0)]
    public int MySubInt { get; set; }
}
```

--------------------------------

### Initialize Program.cs for Orleans

Source: https://learn.microsoft.com/en-us/dotnet/orleans/quickstarts/build-your-first-orleans-app

Replace the contents of Program.cs with the basic Orleans setup.

```csharp
using Orleans.Runtime;

var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();
```

--------------------------------

### Configure Orleans client with IHost

Source: https://learn.microsoft.com/en-us/dotnet/orleans/tutorials-and-samples/overview-helloworld

This example demonstrates configuring the client using IHost and UseOrleansClient, which sets up localhost clustering and cluster/service IDs.

```csharp
public static async Task ClientMain(string[] args)
{
    using IHost host = Host.CreateDefaultBuilder(args)
        .UseOrleansClient(clientBuilder =>
        {
            clientBuilder.UseLocalhostClustering()
                .Configure<ClusterOptions>(options =>
                {
                    options.ClusterId = "dev";
                    options.ServiceId = "HelloWorldApp";
                });
        })
        .ConfigureLogging(logging => logging.AddConsole())
        .Build();

    await host.StartAsync();

    var client = host.Services.GetRequiredService<IClusterClient>();
    Console.WriteLine("Client successfully connected to silo host");

    await DoClientWork(client);

    await host.StopAsync();
}
```

--------------------------------

### Install Microsoft.Orleans.OrleansTelemetryConsumers.AI

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the telemetry consumer for Azure Application Insights.

```PowerShell
Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.AI
```

--------------------------------

### Install Microsoft.Orleans.GrainDirectory.AdoNet via .NET CLI

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/grain-directory

Installs the Orleans ADO.NET grain directory NuGet package.

```.NET CLI
dotnet add package Microsoft.Orleans.GrainDirectory.AdoNet

```

--------------------------------

### Configure client using ClientBuilder

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/client-configuration

Demonstrates manual client configuration using ClientBuilder, including clustering options and application parts.

```csharp
public static async Task ConfigureClient(string connectionString)
{
    var client = new ClientBuilder()
        .Configure<ClusterOptions>(options =>
        {
            options.ClusterId = "my-first-cluster";
            options.ServiceId = "MyOrleansService";
        })
        .UseAzureStorageClustering(
            options => options.ConfigureTableServiceClient(connectionString))
        .ConfigureApplicationParts(
            parts => parts.AddApplicationPart(
                typeof(IValueGrain).Assembly))
        .Build();

    await client.Connect();
}
```

--------------------------------

### Register a Startup Task Delegate

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/startup-tasks

Register a delegate as a startup task using the AddStartupTask extension method on ISiloBuilder.

```csharp
siloBuilder.AddStartupTask(
    async (IServiceProvider services, CancellationToken cancellation) =>
    {
        var grainFactory = services.GetRequiredService<IGrainFactory>();
        var grain = grainFactory.GetGrain<IMyGrain>("startup-task-grain");
        await grain.Initialize();
    });
```

--------------------------------

### Install Microsoft.Orleans.OrleansCodeGenerator

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the package that includes the run-time code generator for Orleans.

```PowerShell
Install-Package Microsoft.Orleans.OrleansCodeGenerator
```

--------------------------------

### Install Microsoft.Orleans.Reminders.DynamoDB

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the plugin for using AWS DynamoDB for storing reminders.

```PowerShell
Install-Package Microsoft.Orleans.Reminders.DynamoDB
```

--------------------------------

### Deploy with parameters file using aspire deploy

Source: https://learn.microsoft.com/en-us/dotnet/orleans/deployment/deploy-to-azure-container-apps

Defines configuration values in a JSON parameter file and passes it to aspire deploy via the --deployment-params-file flag. Recommended for complex deployment configurations.

```JSON
{
  "location": "eastus",
  "environment": "production",
  "resourceGroupName": "my-orleans-app-rg"
}

```

```Bash
aspire deploy --deployment-params-file deployment-params.json

```

--------------------------------

### Install Microsoft.Orleans.OrleansTelemetryConsumers.Counters

Source: https://learn.microsoft.com/en-us/dotnet/orleans/resources/nuget-packages

Installs the Windows Performance Counters implementation of the Orleans Telemetry API.

```PowerShell
Install-Package Microsoft.Orleans.OrleansTelemetryConsumers.Counters
```

--------------------------------

### Configure Orleans Client with Host Builder

Source: https://learn.microsoft.com/en-us/dotnet/orleans/host/configuration-guide/local-development-configuration

Example of a Program.cs file using Microsoft.Extensions.Hosting to configure and run an Orleans client with localhost clustering.

```csharp
using Microsoft.Extensions.Hosting;

using IHost host = Host.CreateDefaultBuilder(args)
    .UseOrleansClient(client =>
    {
        client.UseLocalhostClustering();
    })
    .UseConsoleLifetime()
    .Build();

await host.StartAsync();
```
Tokens:
Raw