Orleans UniversalSilo Quick Start

Here’s how you can quickly get started with Orleans:

1. Install the templates

dotnet new --install Orleans.Contrib.UniversalSilo.Templates

This should print out the list of installed templates, including the following:

$ dotnet new --install Orleans.Contrib.UniversalSilo.Templates
  Restore completed in 660.35 ms.

...

Templates                                         Short Name                   Language          Tags
----------------------------------------------------------------------------------------------------------------------------------------------------
Console Application                               console                      [C#], F#, VB      Common/Console
Class library                                     classlib                     [C#], F#, VB      Common/Library
...
Orleans: Silo And Client                          orleans-silo-and-client      [C#], F#          Orleans/Contrib/Universal Silo/Silo And Client
Orleans: Standalone Client                        orleans-client               [C#], F#          Orleans/Contrib/Universal Silo/Standalone Client
Orleans: Standalone Silo                          orleans-silo                 [C#], F#          Orleans/Contrib/Universal Silo/Standalone Silo
Orleans: WebAPI Direct Client                     orleans-webapi               [C#], F#          Orleans/Contrib/Universal Silo/WebApi Direct Client
...
Solution File                                     sln                                            Solution
Protocol Buffer File                              proto                                          Web/gRPC

Examples:
    dotnet new mvc --auth Individual
    dotnet new react
    dotnet new --help

2. Create an application with a name like HelloOrleansWorld.

$ dotnet new orleans-webapi --name HelloOrleansWorld
The template "Orleans: WebAPI Direct Client" was created successfully.

This will create a fully-functional C# application in the HelloOrleansWorld folder.

You can also choose to generate the project in F# by using the following command:

$ dotnet new orleans-webapi --name HelloOrleansWorld --language F#
The template "Orleans: WebAPI Direct Client" was created successfully.

3. Inspect the sample app

$ cd HelloOrleansWorld
$ ls -al
total 31
drwxr-xr-x 1 johnaz 4096    0 Apr 30 09:50 ./
drwxr-xr-x 1 johnaz 4096    0 Apr 30 09:50 ../
-rw-r--r-- 1 johnaz 4096  124 Apr 30 09:50 .dockerignore
drwxr-xr-x 1 johnaz 4096    0 Apr 30 09:50 .github/
-rw-r--r-- 1 johnaz 4096 3266 Apr 30 09:50 .gitignore
-rw-r--r-- 1 johnaz 4096  206 Apr 30 09:50 docker-compose.yml
-rw-r--r-- 1 johnaz 4096 2119 Apr 30 09:50 Dockerfile
drwxr-xr-x 1 johnaz 4096    0 Apr 30 09:51 grain-controllers/
drwxr-xr-x 1 johnaz 4096    0 Apr 30 09:51 grains/
drwxr-xr-x 1 johnaz 4096    0 Apr 30 09:50 grain-tests/
drwxr-xr-x 1 johnaz 4096    0 Apr 30 09:50 HelloOrleansWorld/
-rw-r--r-- 1 johnaz 4096 2578 Apr 30 09:50 HelloOrleansWorld.sln
-rw-r--r-- 1 johnaz 4096 2720 Apr 30 09:50 Makefile
-rw-r--r-- 1 johnaz 4096  223 Apr 30 09:50 tye.yaml

You will notice that it contains:

A console application project named HelloOrleansWorld which is the host application
A class library project for grains where the grain interfaces and implementations are held
A class library project for grain-controllers where controllers are provided to expose grain methods over WebAPI
A xunit test project where grains can be tested in a test cluster, with examples of how to do unit- and property-based- testing
A solution file to coordinate the projects together
A Makefile script to help you with the incantations to use whilst developing. You do not need to know make to use it
A Dockerfile script to package your application into a Docker container. You do not need to have Docker installed if you do not want to use it
.gitignore and .dockerignore files to help keep your working set clean
A .github folder which contains a simple CI pipeline ready to build your library if you commit it to a GitHub repository

[Experimental]

A tye.yaml script to build, run and deploy your application via Tye
A docker-compose.yml script to orchestrate a multi-node cluster on your local machine using Docker Compose

In future, there will be scripts to help you set up Azure CI pipelines & AKS clusters, deploy to Kubernetes, and so forth.

4. Build, Test and Run the sample app.

$ dotnet build HelloOrleansWorld.sln
Microsoft (R) Build Engine version 16.5.0+d4cbfca49 for .NET Core
Copyright (C) Microsoft Corporation. All rights reserved.

  Restore completed in 1.61 sec for ...\HelloOrleansWorld\grains\grains.csproj.
  Restore completed in 1.61 sec for ...\HelloOrleansWorld\grain-controllers\grain-controllers.csproj.
  Restore completed in 2.43 sec for ...\HelloOrleansWorld\HelloOrleansWorld\HelloOrleansWorld.csproj.
  Restore completed in 2.45 sec for ...\HelloOrleansWorld\grain-tests\grain-tests.csproj.
  Orleans.CodeGenerator - command-line = SourceToSource ...\HelloOrleansWorld\grains\obj\Debug\netcoreapp3.1\grains.orleans.g.args.txt
  grains -> ...\HelloOrleansWorld\grains\bin\Debug\netcoreapp3.1\grains.dll
  grain-controllers -> ...\HelloOrleansWorld\grain-controllers\bin\Debug\netcoreapp3.1\grain-controllers.dll
  grain-tests -> ...\HelloOrleansWorld\grain-tests\bin\Debug\netcoreapp3.1\grain-tests.dll
  HelloOrleansWorld -> ...\HelloOrleansWorld\HelloOrleansWorld\bin\Debug\netcoreapp3.1\HelloOrleansWorld.dll

Build succeeded.
    0 Warning(s)
    0 Error(s)

Time Elapsed 00:00:16.81

$ dotnet test HelloOrleansWorld.sln
Test run for ...\HelloOrleansWorld\grain-tests\bin\Debug\netcoreapp3.1\grain-tests.dll(.NETCoreApp,Version=v3.1)
Microsoft (R) Test Execution Command Line Tool Version 16.5.0
Copyright (c) Microsoft Corporation.  All rights reserved.

Starting test execution, please wait...

A total of 1 test files matched the specified pattern.

Test Run Successful.
Total tests: 4
     Passed: 4
 Total time: 16.8750 Seconds

Don’t forget to allow the firewall configuration in the next step.

$ dotnet run --project HelloOrleansWorld/HelloOrleansWorld.csproj
info: SiloConfigurator[0]
      Clustering mode from environment is: HostLocal
info: SiloConfigurator[0]
      Connection string from environment is:
info: SiloConfigurator[0]
      Blanking connection string because we are running with HostLocal clustering
info: SiloConfigurator[0]
      Finally configuring with clustering mode [HostLocal] with connection string []
info: SiloConfigurator[0]
      Persistence mode from environment is: InMemory
info: SiloConfigurator[0]
      Connection string from environment is:
info: SiloConfigurator[0]
      Finally configuring with persistence mode [InMemory] with connection string []
info: SiloConfigurator[0]
      Using the loopback address for [HostLocal]
info: SiloConfigurator[0]
      Development Clustering running on [127.0.0.1]:[11111]
info: SiloConfigurator[0]
      Configuring Endpoints and Silo Address for clustering mode HostLocal [127.0.0.1:(11111, 30000)]
info: SiloConfigurator[0]
      Configuring Persistence for InMemory []
...
...
-------------- Started silo S127.0.0.1:11111:325957930, ConsistentHashCode 26F31827 --------------
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: http://localhost:5000
info: Microsoft.Hosting.Lifetime[0]
      Now listening on: https://localhost:5001
info: Orleans.Hosting.SiloHostedService[0]
      Starting Orleans Silo.
...
...
info: Orleans.Hosting.SiloHostedService[0]
      Orleans Silo started.
info: Microsoft.Hosting.Lifetime[0]
      Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0]
      Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0]
      Content root path: ...\HelloOrleansWorld\HelloOrleansWorld
...
...

Now fire up a browser and point it to https://localhost:5001/swagger/index.html and you will be presented with the API for a simple calculator which knows how to add two numbers.

Try it out. You are exercising a grain-based calculator!

You now have is a fully functional Orleans-based application exposing its functionality via a WebApi front end.

orleans-contrib-universalsilo

An opinionated, batteries-included, set of templates and libraries to enable you to easily start developing applications with Microsoft Orleans on Azure.

Orleans UniversalSilo Quick Start