This document discusses Microsoft Orleans and provides an overview of getting started with Orleans, including setting up a development environment and deployment workflows. It introduces Orleans Universal Silo, an open source project that provides templates and targets to simplify Orleans development. Templates are provided to generate a basic web API project along with targets for local development, testing, building Docker images, and deploying to Kubernetes or Azure Kubernetes Service (AKS).

1. Microsoft Orleans
The Easy Way
JOHN S AZARIAH
PRINCIPAL SDE, MICROSOFT CORP
@JOHNAZARIAH

2. Introduction

3. Getting Started Is (mostly) Simple
• https://dotnet.github.io/orleans/
• https://gitter.im/dotnet/orleans
• https://devblogs.microsoft.com/dotnet/orleans-3-0/
• Blogs,Videos, ConferenceTalks

4. The first hurdles
• Concept of Virtual Actors
• Idiosyncratic Code Layout (Grain Interfaces, Grains, …)
• Declarative persistence
• State management
• Query patterns, Fan-out, Fan-in and performance implications
• Silos, Clients, Configuration
• Failure modes - split-brain scenarios, concurrency
• Advanced Concepts (Reentrancy, Timers, Reminders,
Streaming, …)

5. My own n00b path
• Writing a simple dummy app which runs locally based on
samples
• Preparing the application to run in the cloud - configuration,
secrets and so on
• Preparing the application to run in clustered mode
• Provisioning and deploying to Azure
• CI/CD considerations - stability, repeatability

6. Orleans
Application
Code Structure
Silo Client
Interface
Implementation
Interface
Client Code

7. Orleans
Application
Code Structure

8. Orleans
Runtime
Components
Client
Silo
Client
Silo
Client
Silo
Load Balancer
Persistence (Grain Storage)
Clustering

9. Orleans Universal Silo

10. Introducing Orleans Universal Silo
• https://github.com/johnazariah/orleans-contrib-universalsilo
• https://www.nuget.org/packages/Orleans.Contrib.UniversalSilo/
• https://www.nuget.org/packages/Orleans.Contrib.UniversalSilo.Te
mplates/
• https://github.com/johnazariah/orleans-contrib-
universalsilo/blob/main/docs/index.md

11. Setting up your work environment
• https://github.com/johnazariah/orleans-contrib-
universalsilo/blob/main/docs/setup-environment-setup.md

12. Getting Started
• Install template library with
dotnet new --install
Orleans.Contrib.UniversalSilo.Templates
• List installed templates
dotnet new --list
• Ensure OrleansWebAPI template is present

13. Getting Started
• Create newWebAPI Direct Client Project
dotnet new orleans-webapi –name Cornflake
• Initialize Git
make init
• Inspect code withVisual Studio
start Cornflake.sln

14. Testing
• All tests are IntegrationTests
• Test Clusters are set up with Host Clustering and In-Memory Storage
• Use Property BasedTesting whenever possible

15. Running
• .NET Generic HostApplication
• Hit http://localhost:5000/swagger/index.html with browser to see
app
• Hit http://localhost:8080/ with browser to see Orleans Dashboard

16. Running
• .NET Generic HostApplication
• Hit http://localhost:5000/swagger/index.html with browser to see
app
• Hit http://localhost:8080/ with browser to see Orleans Dashboard

17. Development Workflow

18. .net CLI targets
• Clean the project with make dotnet-clean.This removes build
artefacts and restores
• Restore, Build andTest the project with make dotnet-test.
• Publish the project to an output folder with make dotnet-publish.
• Run the artefacts in the output folder with make dotnet-run.
• make dotnet-all is an alias target which does dotnet-clean dotnet-
test dotnet-publish dotnet-run.This will implicitly rebuild, test,
republish and run the project as you make changes in your code
and re-run it.

19. Docker targets
• Build the docker image with make docker-build
• Run the image with HostLocal clustering mode with make docker-
run.
• Run with Azure clustering mode against local Azure Storage
Emulator with make docker-run-local-ase
• Stop all running containers with make docker-stop
• List the docker images you have built with make docker-list

20. Local Kubernetes Deployment
• Ensure you are running with the correct context (docker-desktop)
• make dotnet-all to build, test and run your project until
satisfactory.
• git commit (to update the hash of the HEAD commit)
• make docker-build to build a docker image with these changes,
tagged with the current branch and commit hash
• make k8s-deploy or make k8s-upgrade to deploy 3 copies of the
latest image into the current k8s context.
• make k8s-status is an alias for kubectl get all

21. Manual AKS deployment
• You can install Azure CLI tools, or just use the docker container.
• Recommend using two shells for this – one for Azure and one for
the Project

22. Manual AKS deployment : Azure Shell
• make az-start fires up an interactive shell inside the officialAzure CLI Docker
image
• make az-login will allow you to use your browser to authenticate againstAzure.
Find the id of the subscription you want.
• make az-sub-set sub=<id you selected above> will set the shell to use the
selected subscription by default.
• Put the org-name and project-name, and the subscription id in Setup.cfg
• make az-new-org should only be run once per organization name.
• make az-new-proj should only be run once per project.
• Put emitted values for paks_storage_connection_string and
oaks_acr_login_token into Setup.cfg

23. Manual AKS deployment : Project Shell
• make aks-prepare to set up the k8s context to the remote AKS
cluster
• make docker-push to push the latest built image to the remote
Azure Container Registry
• make k8s-deploy to deploy the remote AKS cluster

24. CI/CD AKS deployment : WIP
• This is the next feature I’m working on

25. Next Steps
• Try these templates and improve them. Pull Requests welcome.
• Get the CI/CD stage completed.This is work-in-progress.
• Use this approach for non-Orleans .NET core generic hosts to
support deployment onAKS
• Work out an integration story with ProjectTye
• Community suggestions

26. Thank you!