Microsoft Orleans

Create your first Microsoft Orleans application

we will introduce the concept of grains and show you how to create and interact with grains in an Orleans application. Grains are the basic building blocks of Orleans applications, and they allow you to create self-contained units of work that can communicate with each other asynchronously.

We will start by creating a simple “hello world” grain and showing you how to invoke it from your Orleans application.

To create your first Orleans application, you will need to follow these steps:

  1. Create a new Orleans project: As mentioned in the previous post, you can create a new Orleans project by selecting the “Orleans” template in your code editor or by using the dotnet new command line tool. This will create a basic project structure with some starter code and configuration files.
  2. Define your grain interface: Grains are the basic building blocks of Orleans applications, and they represent self-contained units of work. To create a grain, you will need to define a grain interface that specifies the methods that can be invoked on the grain.

For example, you might define a grain interface called IHelloWorldGrain like this:

public interface IHelloWorldGrain : IGrainWithGuidKey
{
    Task<string> SayHello(string name);
}

This grain interface defines a single method called SayHello that takes a string parameter and returns a string.

  1. Implement your grain: Next, you will need to implement your grain by creating a class that implements your grain interface. For example, you might implement the IHelloWorldGrain interface like this:
public class HelloWorldGrain : Grain, IHelloWorldGrain
{
    public Task<string> SayHello(string name)
    {
        return Task.FromResult($"Hello, {name}!");
    }
}

This grain implementation simply returns a string that says “Hello” to the specified name.

  1. Create a grain client: To invoke your grain from your Orleans application, you will need to create a grain client. A grain client is a special object that acts as a proxy for your grain and allows you to invoke methods on it remotely.

To create a grain client, you will need to use the GrainClient class provided by Orleans. For example, you might create a grain client like this:

var grainClient = GrainClient.GrainFactory.GetGrain<IHelloWorldGrain>(Guid.NewGuid());

This creates a new grain client for the IHelloWorldGrain interface and assigns it a unique identifier.

  1. Invoke your grain: Finally, you can invoke your grain by calling the appropriate method on your grain client. For example, you might invoke the SayHello method like this:
string result = await grainClient.SayHello("Alice");

This will invoke the SayHello method on your grain and return the result as a string.

That’s it! With these steps, you should have a basic Orleans application up and running. In the next post, we will explore some of the key features and tools that Orleans provides for building distributed applications, including support for distributed caching, messaging, and storage.