Microsoft Orleans is a cross platform framework for distributed applications. It’s based upon the Actor model which represents a lightweight, concurrent, immutable objects encapsulating state. <\/p>\n
Basic Concepts<\/strong><\/p>\n A Grain<\/em> is a virtual actor and one of several Orleans primitives. A Grain is an entity which comprises of<\/p>\n where an identity is a user-defined key.<\/p>\n Grains are automatically instantiated on demand by the Orleans runtime and have a managed lifecycle with the runtime activating\/deactivating grains as well as placing\/locating grains as required.<\/p>\n A Silo<\/em> is a primitive which hosts one or more Grains. A group of silos run as a cluster and in this mode coordinates and distributes work. <\/p>\n Orleans can handle persistence, timers and reminders along with flexible grain placement and versioning.<\/p>\n Use cases<\/strong><\/p>\n Whilst grains can be stateless, the “sweet spot” for using Orleans is where you require distributed, durable and concurrent state management without locks etc. Long running stateful process such as event driven workflows are very much in the Orleans world.<\/p>\n Where Orleans is not the best solution include stateless, computer heavy tasks, these are better suited to Azure functions (for example). In such situations Orleans just adds complexity. <\/p>\n Lifecycle<\/strong><\/p>\n Orleans automatically manages the lifecycle of grains. A grain may be in one of the following states activating<\/em>, active<\/em>, deactivating<\/em> and persisted<\/em>. Persisted<\/em> maybe wasn’t the state you first thought of when looking at the progress through other states. Let’s look at the states in a little more depth (although probably fairly self explanatory)<\/p>\n The framework takes care of the life cycle and allows the developer to just concentrate on using grains.<\/p>\n The Silo lifecycle<\/strong><\/p>\n The silo’s lifecycle goes something like the following<\/p>\n Concurrency<\/strong><\/p>\n Grains are virtual actors and hence based upon the Actor model which essentially has a single thread that accepts request\/messages. Hence when a grain is processing a request it’s in a busy state and in the default, turn based concurrency, other requests are queued. It’s possible to override turn-based concurrency to handle multiple messages on the same thread but this does come with potential risks around sharing a threads.<\/p>\n Orleans maintains a relative small thread pool which is determined by the number of CPU cores in the system, therefore we must still be careful around any potential blocking of threads. Grains can use the .NET thread pool but this should be fairly rare and using async\/await should be used.<\/p>\n Mesage flow<\/strong><\/p>\n Requests for a grain are passed from client to silo and then the request is passed onto the grain. When the grain has completed it’s work and if a response is required this will pass back to the silo and onto the client.<\/p>\n Let’s write some code<\/strong><\/p>\n Let’s get to writing the equivalent of “Hello World” by creating two Console projects, mine are named Client and Silo. However I also want some interface and implementation of a HelloGrain, so you’ll need to create two libraries. I’ve named mine GrainInterfaces and Grains (not very imaginative I admit).<\/p>\n In the Client project add the following nuget package Microsoft.Orleans.Client<\/em>, so my packages are as follows in the .csproj<\/p>\n Now in the Silot project add Microsoft.Orleans.Hosting.Server<\/em>, I’m also wanting to host in Kubernetes so added Microsoft.Orleans.Hosting.Kuberneres<\/em> and Microsoft.Clustering.Kuberneres<\/em>. Finally I want to use the OrleansDashboard, so add the OrleansDashboard<\/em> package, hence my .csproj looks like this<\/p>\n Notice I also have the Microsoft.Extensions packaged to include logging and to create the host.<\/p>\n For the GrainInterfaces project add the package Microsoft.Orleans.Sdk<\/em> so the GrainInterfaces .csproj has this<\/p>\n and finally add the same to the Grains project but also let’s add Microsoft.Extensions.Logging.Abstractions<\/em> for us to do some logging, so the .csproj should look like this<\/p>\n For the GrainInterfaces add an interface IHello.cs which looks like this<\/p>\n Add a project reference in the Client to this project.<\/p>\n Next up, the Grains project has a new class named HelloGrain.cs which looks like this<\/p>\n For the server code, edit the Program.cs within the Client project as follows<\/p>\n For the server code, edit the Program.cs within the Silo project as follows<\/p>\n If we’re wanting to run these project from a single solution then don’t forget to go to Visual Studio’s solution, right mouse click and select Configure Startup Projects from here select the Common Properties | Configure Startup Projects and then Multiple startup projects, set the Silo and Client project actions to Start<\/em>.<\/p>\n Persistence<\/strong><\/p>\n As mentioned previously grains can be have their state persisted by Orleans. If we edit the silo project, Program.cs we can add various types of persistence, table store, SQL database etc. but also for testing we can use an in memory storage.<\/p>\n We just add the following to the UseOrleans method<\/p>\n Now in our HelloGrain we can add persistence as easily as the following, add the PersistanceState attribute as a ctor parameter for the IPersistentState object to be injected<\/p>\n The state name here is “hello” and the storageName should match the storage we set up in the Silo project.<\/p>\n Now to save data on the state we just write the following in the SayHello method<\/p>\n Here’s a very simple State object example<\/p>\n Microsoft Orleans is a cross platform framework for distributed applications. It’s based upon the Actor model which represents a lightweight, concurrent, immutable objects encapsulating state. Basic Concepts A Grain is a virtual actor and one of several Orleans primitives. A Grain is an entity which comprises of identity + behaviour + state where an identity […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[156,765],"tags":[],"class_list":["post-11980","post","type-post","status-publish","format-standard","hentry","category-actor-model","category-orleans"],"jetpack_sharing_enabled":true,"jetpack_featured_media_url":"","_links":{"self":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts\/11980","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/comments?post=11980"}],"version-history":[{"count":5,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts\/11980\/revisions"}],"predecessor-version":[{"id":12023,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/posts\/11980\/revisions\/12023"}],"wp:attachment":[{"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/media?parent=11980"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/categories?post=11980"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/putridparrot.com\/blog\/wp-json\/wp\/v2\/tags?post=11980"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}\r\nidentity + behaviour + state\r\n<\/pre>\n
\n
\n
\r\n<PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.10" \/>\r\n<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.10" \/>\r\n<PackageReference Include="Microsoft.Orleans.Client" Version="9.2.1" \/>\r\n<\/pre>\n
\r\n<PackageReference Include="Microsoft.Extensions.Hosting" Version="9.0.10" \/>\r\n<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.10" \/>\r\n<PackageReference Include="Microsoft.Orleans.Hosting.Kubernetes" Version="9.2.1" \/>\r\n<PackageReference Include="Microsoft.Orleans.Server" Version="9.2.1" \/>\r\n<PackageReference Include="Orleans.Clustering.Kubernetes" Version="8.2.0" \/>\r\n<PackageReference Include="OrleansDashboard" Version="8.2.0" \/>\r\n<\/pre>\n
\r\n<PackageReference Include="Microsoft.Orleans.Sdk" Version="9.2.1" \/>\r\n<\/pre>\n
\r\n<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="9.0.10" \/>\r\n<PackageReference Include="Microsoft.Orleans.Sdk" Version="9.2.1" \/>\r\n<\/pre>\n
\r\npublic interface IHello : IGrainWithIntegerKey\r\n{\r\n ValueTask<string> SayHello(string greeting);\r\n}\r\n<\/pre>\n\r\npublic class HelloGrain(ILogger<HelloGrain> logger) : Grain, IHello\r\n{\r\n private readonly ILogger _logger = logger;\r\n\r\n ValueTask<string> IHello.SayHello(string greeting)\r\n {\r\n _logger.LogInformation("""\r\n SayHello message received: "{Greeting}"\r\n """,\r\n greeting);\r\n\r\n return ValueTask.FromResult($"""\r\n Client said: "{greeting}"\r\n """);\r\n }\r\n\r\n public override Task OnDeactivateAsync(DeactivationReason reason, CancellationToken cancellationToken)\r\n {\r\n if(reason.ReasonCode == DeactivationReasonCode.ShuttingDown)\r\n {\r\n MigrateOnIdle();\r\n }\r\n\r\n return base.OnDeactivateAsync(reason, cancellationToken);\r\n }\r\n<\/pre>\n\r\nusing Microsoft.Extensions.Logging;\r\nusing Microsoft.Extensions.Hosting;\r\nusing Microsoft.Extensions.DependencyInjection;\r\nusing GrainInterfaces;\r\n\r\nvar builder = Host.CreateDefaultBuilder(args)\r\n .UseOrleansClient(client =>\r\n {\r\n client.UseLocalhostClustering();\r\n })\r\n .ConfigureLogging(logging => logging.AddConsole())\r\n .UseConsoleLifetime();\r\n\r\nusing var host = builder.Build();\r\nawait host.StartAsync();\r\n\r\nvar client = host.Services.GetRequiredService<IClusterClient>();\r\n\r\nvar friend = client.GetGrain<IHello>(0);\r\nstring response = await friend.SayHello("Hi Orleans");\r\n\r\nConsole.WriteLine($"""\r\n {response}\r\n\r\n Press any key to exit...\r\n """);\r\n\r\nConsole.ReadKey();\r\n\r\nawait host.StopAsync();\r\n<\/pre>\n\r\nusing Microsoft.Extensions.Hosting;\r\nusing Microsoft.Extensions.Logging;\r\n\r\nvar builder = Host.CreateDefaultBuilder(args)\r\n .UseOrleans(silo =>\r\n {\r\n silo.UseLocalhostClustering()\r\n .ConfigureLogging(logging => logging.AddConsole());\r\n silo.UseDashboard(options => \r\n {\r\n options.HostSelf = true; \/\/ Enables embedded web server\r\n options.Port = 7000; \/\/ Default port\r\n });\r\n })\r\n .UseConsoleLifetime();\r\n\r\nusing IHost host = builder.Build();\r\n\r\nawait host.RunAsync();\r\n<\/pre>\n\r\nsilo.AddMemoryGrainStorage("docStore");\r\n\/\/ Or Azure Table storage\r\n\/\/ silo.AddAzureTableGrainStorage("documentStore", options =>\r\n\/\/ {\r\n\/\/ options.ConnectionString = "<your-connection-string>";\r\n\/\/ });\r\n<\/pre>\n\r\npublic class HelloGrain(\r\n [PersistentState("hello", "docStore")] IPersistentState<State> state, \r\n ILogger<HelloGrain> logger) : Grain, IHello\r\n<\/pre>\n\r\nstate.State.Data = greeting;\r\nawait state.WriteStateAsync();\r\n<\/pre>\n
\r\npublic class State\r\n{\r\n public string? Data { get; set; }\r\n}\r\n<\/pre>\n","protected":false},"excerpt":{"rendered":"