{"id":36,"date":"2024-02-13T14:06:09","date_gmt":"2024-02-13T11:06:09","guid":{"rendered":"http:\/\/caitiem.com\/?p=36"},"modified":"2024-02-13T15:28:50","modified_gmt":"2024-02-13T12:28:50","slug":"creating-restful-services-using-orleans","status":"publish","type":"post","link":"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/","title":{"rendered":"Creating RESTful Services using\u00a0Orleans"},"content":{"rendered":"\n<p>After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye.<\/p>\n\n\n\n<blockquote class=\"wp-block-quote is-layout-flow wp-block-quote-is-layout-flow\">\n<p>.NET\u2019s actor model uses static factories, RPC Interfaces and code-gen client proxies for comms, WCF all over again: http:\/\/t.co\/PyIq291Kvh<\/p>\n\n\n\n<p>\u2014 Demis Bellot (@demisbellot) April 3, 2014<\/p>\n<\/blockquote>\n\n\n\n<p>I think this is a bit of a misunderstanding of how Orleans can and should be used in production&nbsp;services, this blog post is an attempt to clarify and demonstrate how to build RESTful, loosely coupled services using Orleans.<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">Orleans Programming Model<\/h3>\n\n\n\n<p>Orleans is a runtime and programming model for building distributed systems, based on the actor model. &nbsp;In the programming model there are a few key terms.<\/p>\n\n\n\n<ul>\n<li><strong>Grains<\/strong> \u2013 The Orleans term for an actor. &nbsp;These are the building blocks of Orleans based services. &nbsp;Every actor has a unique identity and encapsulates behavior and mutable state. &nbsp;Grains are isolated from one another and can only communicate via messages. &nbsp;As a developer this is the level you write your code at.<\/li>\n\n\n\n<li><strong>Silos<\/strong> \u2013&nbsp;Every machine Orleans manages is a Silo. &nbsp;A Silo contains grains, and&nbsp;houses the Orleans runtime which performs operations like grain instantiation and look-up.<\/li>\n\n\n\n<li><strong>Orleans Clients<\/strong> \u2013 clients are non-silo code which makes calls to Orleans Grains. &nbsp;We\u2019ll get back to where this should live in your architecture later.<\/li>\n<\/ul>\n\n\n\n<p>In order to create Grains developers write&nbsp;code in two libraries. &nbsp;GrainInterfaces.dll and Grains.dll. &nbsp;The GrainInterfaces library defines a strongly-typed interface for a grain. &nbsp;The Method names and Properties must all be asynchronous, and these define what types of messages can be passed in the system. All Grain Interfaces must inherit from Orleans.IGrain. \/\/\/ &amp;lt;summary&amp;gt; \/\/\/ Orleans grain communication interface IHello \/\/\/ &amp;lt;\/summary&amp;gt; public interface IHello : Orleans.IGrain { Task&amp;lt;string&amp;gt; SayHello(); Task&amp;lt;string&amp;gt; SayGoodbye(); }<\/p>\n\n\n\n<p>The Implementation of the Grains should be defined in the a separate Grains Library. All Grain implementations should implement its corresponding Grain Interface, and inherit from Orleans.GrainBase. \/\/\/ &amp;lt;summary&amp;gt; \/\/\/ Orleans grain implementation class HelloGrain. \/\/\/ &amp;lt;\/summary&amp;gt; public class HelloGrain : Orleans.GrainBase, HelloWorldInterfaces.IHello { Task&amp;lt;string&amp;gt; HelloWorldInterfaces.IHello.SayHello() { return Task.FromResult(&amp;quot; I say: Hello! &amp;quot; + DateTime.UtcNow.ToLongDateString()); } Task&amp;lt;string&amp;gt; HelloWorldInterfaces.IHello.SayGoodbye() { return Task.FromResult(&amp;quot;I say: Goodbye! &amp;quot; + DateTime.UtcNow.ToLongDateString()); } }<\/p>\n\n\n\n<p>At compile time code is generated in the GrainInterfaces dll, to implement the code needed by the Silos to perform message passing, grain look-up etc\u2026 This code, by default will be under GrainInterfaces\/properites\/orleans.codegen.cs &nbsp;There are a lot of interesting things happening in this file, I recommend taking a look if you want to understand the guts of Orleans a bit more. &nbsp;Below I\u2019ve pulled out snippets of the generated code.<\/p>\n\n\n\n<p>Every GrainInterface defined in the library will have a corresponding Factory Class and GrainReference Class generated. &nbsp;The Factory Class contains GetGrain methods. &nbsp;These methods take in the unique grain identifier and creates a GrainReference. &nbsp;If you look below you will see that the HelloGrainReference has corresponding SayHello and SayGoodbye methods with the same method signature as the Interface. public class HelloFactory { public static IHello GetGrain(long primaryKey) { return Cast(GrainFactoryBase.MakeGrainReferenceInternal(typeof(IHello), 1163075867, primaryKey)); } public static IHello Cast(IAddressable grainRef) { return HelloReference.Cast(grainRef); } [System.SerializableAttribute()] [Orleans.GrainReferenceAttribute(&amp;quot;HelloWorldInterfaces.IHello&amp;quot;)] internal class HelloReference : Orleans.GrainReference, IHello, Orleans.IAddressable { public static IHello Cast(IAddressable grainRef) { return (IHello) GrainReference.CastInternal(typeof(IHello), (GrainReference gr) =&amp;gt; { return new HelloReference(gr);}, grainRef, 1163075867); } protected internal HelloReference(GrainReference reference) : base(reference) { } public System.Threading.Tasks.Task&amp;lt;string&amp;gt; SayHello() { return base.InvokeMethodAsync&amp;lt;System.String&amp;gt;(-1732333552, new object[] {}, TimeSpan.Zero ); } public System.Threading.Tasks.Task&amp;lt;string&amp;gt; SayGoodbye() { return base.InvokeMethodAsync&amp;lt;System.String&amp;gt;(-2042227800, new object[] {}, TimeSpan.Zero ); } } }<\/p>\n\n\n\n<p>In an Orleans Client you would send a message to the HelloGrain using the following code. IHello grainRef = HelloFactory.GetGrain(0); string msg = await grainRef.SayHello(&amp;quot;Hello Orleans!&amp;quot;);<\/p>\n\n\n\n<p>So at this point if you are thinking, this looks like RPC, you are right. Orleans Clients and Orleans Grains communicate with one another via Remote Procedure Calls, that are defined in the GrainInterfaces. Messages are passed via TCP connections between Orleans Clients&nbsp;and Grains. Grain to Grain calls are also sent over a TCP connection if they are on different machines. &nbsp;This is really performant, and provides a nice programming model. &nbsp;As a developer you just invoke a method, you don\u2019t care where the code actually executes, one of the benefits of Location Transparency.<\/p>\n\n\n\n<p>Ok stay with me, Deep Breaths. &nbsp;Project Orleans is not trying to re-create WCF with hard coded data contracts and tight coupling between services &amp; clients. Personally I hate tight coupling, ask me about BLFs, the wire-struct in the original Halo games, if you want to hear an entertaining story, but I digress\u2026<\/p>\n\n\n\n<h3 class=\"wp-block-heading\">RESTful Service Architectures<\/h3>\n\n\n\n<p>Orleans is a really powerful tool to help implement the middle tier of a traditional 3-tiered architecture. The Front-End, which is an Orleans Client, The Silos running your Grains and performing application level logic, and your Persistent Storage.<\/p>\n\n\n\n<p>On The Front-End you can define a set of RESTful APIs (or whatever other protocol you want for that matter), which then routes incoming calls to Orleans Grains to handle application specific logic, by using the Factory methods generated in GrainInterfaces dll. &nbsp;In addition the Front-End can Serialize\/Deserialize messages into the loosely coupled wire-level format of your choosing (JSON, Protocol Buffers, Avro, etc\u2026).<\/p>\n\n\n\n<p>By structuring your services this way, you are completely encapsulating the dependency on Orleans within the service itself,&nbsp;while presenting a RESTful API with a loosely coupled wire struct format. &nbsp;This way the clients can happily communicate with your service without fear of tight coupling or RPC.<\/p>\n\n\n\n<p>The below code uses ASP.NET WebApi to create a Front End Http Controller that interacts with the Hello Grain. public class HelloController : ApiController { \/\/ GET api\/Hello\/{userId} public async Task&amp;lt;string&amp;gt; Get(long userId) { IHello grain = HelloFactory.GetGrain(userId); var response = await grain.SayHello(); return response; } \/\/ DELETE api\/Hello\/{userId} public async Task Delete(long userId) { IHello grain = HelloFactory.GetGrain(userId); var response = await grain.SayGoodbye(); return; } }<\/p>\n\n\n\n<p>While this is a contrived example, you can see how you can map your REST resources to individual grains.<\/p>\n\n\n\n<p>This is the architectural approach Halo 4 Services took when deploying Orleans. &nbsp;We built a custom, light weight, super fast front-end that supported a set of Http APIs. &nbsp;Http Requests were minimally processed by the front-end and then routed to the Orleans Grains for processing. &nbsp;This allowed the game code and the services to evolve independently from one another.<\/p>\n\n\n\n<p>The above example uses ASP.NET Web API, if you want something lighter weight checkout OWIN\/Project Katana.<\/p>\n\n\n\n<p>*HelloGrain Code Samples were taken from Project \u201cOrleans\u201d Samples available on Codeplex, and slightly modified.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye. .NET\u2019s actor model uses static factories, RPC Interfaces and code-gen client proxies for comms, WCF all over again: http:\/\/t.co\/PyIq291Kvh \u2014 Demis Bellot (@demisbellot) April 3, 2014 I think&#8230;<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[4],"tags":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v21.6 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>Creating RESTful Services using\u00a0Orleans - caitiem.com<\/title>\n<meta name=\"description\" content=\"After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye.\" \/>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Creating RESTful Services using\u00a0Orleans - caitiem.com\" \/>\n<meta property=\"og:description\" content=\"After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye.\" \/>\n<meta property=\"og:url\" content=\"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/\" \/>\n<meta property=\"og:site_name\" content=\"caitiem.com\" \/>\n<meta property=\"article:published_time\" content=\"2024-02-13T11:06:09+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2024-02-13T12:28:50+00:00\" \/>\n<meta name=\"author\" content=\"caiti335\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"caiti335\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"5 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/\",\"url\":\"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/\",\"name\":\"Creating RESTful Services using\u00a0Orleans - caitiem.com\",\"isPartOf\":{\"@id\":\"https:\/\/www.caitiem.com\/#website\"},\"datePublished\":\"2024-02-13T11:06:09+00:00\",\"dateModified\":\"2024-02-13T12:28:50+00:00\",\"author\":{\"@id\":\"https:\/\/www.caitiem.com\/#\/schema\/person\/0ea20eb328afb663a23dc72ebeced8c0\"},\"description\":\"After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye.\",\"breadcrumb\":{\"@id\":\"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"\u0413\u043b\u0430\u0432\u043d\u0430\u044f \u0441\u0442\u0440\u0430\u043d\u0438\u0446\u0430\",\"item\":\"https:\/\/www.caitiem.com\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Creating RESTful Services using\u00a0Orleans\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/www.caitiem.com\/#website\",\"url\":\"https:\/\/www.caitiem.com\/\",\"name\":\"caitiem.com\",\"description\":\"\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/www.caitiem.com\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/www.caitiem.com\/#\/schema\/person\/0ea20eb328afb663a23dc72ebeced8c0\",\"name\":\"caiti335\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/www.caitiem.com\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/08e6287ee41d891ed906aa45a965ba3c?s=96&d=mm&r=g\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/08e6287ee41d891ed906aa45a965ba3c?s=96&d=mm&r=g\",\"caption\":\"caiti335\"},\"url\":\"https:\/\/www.caitiem.com\/author\/caiti335\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Creating RESTful Services using\u00a0Orleans - caitiem.com","description":"After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye.","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/","og_locale":"en_US","og_type":"article","og_title":"Creating RESTful Services using\u00a0Orleans - caitiem.com","og_description":"After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye.","og_url":"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/","og_site_name":"caitiem.com","article_published_time":"2024-02-13T11:06:09+00:00","article_modified_time":"2024-02-13T12:28:50+00:00","author":"caiti335","twitter_card":"summary_large_image","twitter_misc":{"Written by":"caiti335","Est. reading time":"5 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/","url":"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/","name":"Creating RESTful Services using\u00a0Orleans - caitiem.com","isPartOf":{"@id":"https:\/\/www.caitiem.com\/#website"},"datePublished":"2024-02-13T11:06:09+00:00","dateModified":"2024-02-13T12:28:50+00:00","author":{"@id":"https:\/\/www.caitiem.com\/#\/schema\/person\/0ea20eb328afb663a23dc72ebeced8c0"},"description":"After the announce of the Orleans preview, there was a lot of discussion on Twitter. \u00a0One comment in particular caught my eye.","breadcrumb":{"@id":"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/"]}]},{"@type":"BreadcrumbList","@id":"http:\/\/www.caitiem.com\/2014\/04\/04\/creating-restful-services-using-orleans\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"\u0413\u043b\u0430\u0432\u043d\u0430\u044f \u0441\u0442\u0440\u0430\u043d\u0438\u0446\u0430","item":"https:\/\/www.caitiem.com\/"},{"@type":"ListItem","position":2,"name":"Creating RESTful Services using\u00a0Orleans"}]},{"@type":"WebSite","@id":"https:\/\/www.caitiem.com\/#website","url":"https:\/\/www.caitiem.com\/","name":"caitiem.com","description":"","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.caitiem.com\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/www.caitiem.com\/#\/schema\/person\/0ea20eb328afb663a23dc72ebeced8c0","name":"caiti335","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/www.caitiem.com\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/08e6287ee41d891ed906aa45a965ba3c?s=96&d=mm&r=g","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/08e6287ee41d891ed906aa45a965ba3c?s=96&d=mm&r=g","caption":"caiti335"},"url":"https:\/\/www.caitiem.com\/author\/caiti335\/"}]}},"_links":{"self":[{"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/posts\/36"}],"collection":[{"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/comments?post=36"}],"version-history":[{"count":1,"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/posts\/36\/revisions"}],"predecessor-version":[{"id":42,"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/posts\/36\/revisions\/42"}],"wp:attachment":[{"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/media?parent=36"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/categories?post=36"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.caitiem.com\/wp-json\/wp\/v2\/tags?post=36"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}