Skip to content
Orleans.FSharp
Menu
Functional Runtime
OverviewContracts and KeysState and LifecycleCalls and DeliveryPlacement and TransactionsComplete Reference
Data and Messaging
SerializationStreamingEvent SourcingServer-Streaming Replies
Hosting and Operations
Silo ConfigurationOrleans DashboardClient ConfigurationTestingSecurityResilienceAdditional APIsAnalyzersCalling from C#
Legacy Archive (Unsupported)
Legacy OverviewGetting StartedHow ToGrain DefinitionAPI ReferenceMigrate from 4.xEvent SourcingSerializationStreamingTestingAdvanced PatternsResilienceRedis ExampleFAQ

Recipes

Section titled “Recipes”

Task-oriented paths through the current functional API.

Looking for the first tutorial? Start with Getting Started. This page assumes you already know how grainContract, grainFor, and FunctionalGrain.ref fit together and sends you directly to the task you need.

Start a new current-API project

Section titled “Start a new current-API project”

Install the published Orleans.FSharp 5.0.1 template:

Terminal window
dotnet new install Orleans.FSharp.Templates@5.0.1
dotnet new orleans-fsharp -n MyApp

Already generated with 5.0.0? Apply the one-line startup correction; updating the template package does not rewrite existing source.

For contributor work against repository changes, clone the repository and install ./orleans-fsharp/templates instead. See Release and Production Status for the stable release and its production boundaries.

Choose the grain shape

Section titled “Choose the grain shape”
Need Start here
Ephemeral state and typed operations Contracts and handlers
Durable state Persistence model
Events as the source of truth Event Sourcing
Read-only operation handleQuery
Push to a client Functional observers
A sequence returned by one call Server-Streaming Replies
Pub/sub between producers and consumers Streaming
Cross-grain ACID work Transactions
Call the actor from C# Calling from C#

Configure the host

Section titled “Configure the host”
Task Guide
Local silo Getting Started
Storage, stream, reminder, or clustering provider Silo Configuration
Standalone client Client Configuration
Orleans Dashboard Dashboard
TLS, call filters, and secret handling Security
Retry, timeout, and circuit breaker Resilience

Evolve a deployed application

Section titled “Evolve a deployed application”

Treat these as separate compatibility gates:

  1. Route old and new callers with contract versioning.
  2. Keep stored state readable with versioned state and upcasters.
  3. Keep journal entries and snapshots readable with versioned events and snapshots.
  4. Prove N/N+1 and rollback with separate processes; see Testing rolling updates.

The Orleans compatibility page records the framework versions exercised by CI and calls out new Orleans capabilities which are not yet wrapped.

Verify the application

Section titled “Verify the application”
  • Unit-test pure transition functions directly.
  • Use a real TestingHost activation for persistence, serialization, reminders, streams, transactions, and lifecycle behavior.
  • Keep bytes written by released serializers as fixtures when durable schemas evolve.
  • Run the closest repository example before copying a provider-specific setup.

See Testing for complete patterns and Examples for runnable projects.

Migration-only material for earlier authoring models is isolated in the unsupported Legacy archive.