Skip to content
Orleans logoMicrosoft Orleans

Quickstart: Orleans Hello World

This quickstart builds the bare minimum Orleans application in one project. The process hosts a silo and calls a grain using the client that Orleans provides inside every silo.

Prerequisites

Section titled “Prerequisites”

Create the project

Section titled “Create the project”

Run the following commands in an empty directory:

Terminal window
dotnet new console --name HelloWorld --framework net10.0
cd HelloWorld
dotnet package add Microsoft.Orleans.Server --version 10.2.2
dotnet package add Microsoft.Extensions.Hosting --version 10.0.9

Microsoft.Orleans.Server includes the Orleans runtime, client APIs, and SDK build tooling.

Define the grain contract

Section titled “Define the grain contract”

Create IHello.cs and define a grain interface:

using Orleans;


namespace HelloWorld;


public interface IHello : IGrainWithStringKey
{
    ValueTask<string> SayHello(string greeting);
}

IGrainWithStringKey identifies the grain by a string key. Grain contracts use asynchronous return types because calls can cross process and network boundaries.

Implement the grain

Section titled “Implement the grain”

Create HelloGrain.cs and implement the grain interface:

using Orleans;


namespace HelloWorld;


public sealed class HelloGrain : Grain, IHello
{
    public ValueTask<string> SayHello(string greeting) =>
        ValueTask.FromResult($"Hello, {greeting}!");
}

Configure Orleans and call the grain

Section titled “Configure Orleans and call the grain”

Replace Program.cs with the following code:

using HelloWorld;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Orleans;


var builder = Host.CreateApplicationBuilder(args);


builder.UseOrleans(siloBuilder =>
{
    siloBuilder.UseLocalhostClustering();
});


using var host = builder.Build();
await host.StartAsync();


var grainFactory = host.Services.GetRequiredService<IGrainFactory>();
var friend = grainFactory.GetGrain<IHello>("friend");
var response = await friend.SayHello("Hi friend");


Console.WriteLine(response);


await host.StopAsync();

UseOrleans adds a silo and its in-process client to the .NET Generic Host. UseLocalhostClustering configures development-only clustering on the local machine.

After the host starts, resolve IGrainFactory, obtain a logical reference to the grain identified by friend, and call it.

Run the app

Section titled “Run the app”
Terminal window
dotnet run

The app prints:

Hello, Hi friend!

Next steps

Section titled “Next steps”