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).
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
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
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
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