Frequently Asked Questions
Section titled “Frequently Asked Questions”What is Orleans.FSharp?
Section titled “What is Orleans.FSharp?”Orleans.FSharp is a functional-first F# authoring layer over Microsoft Orleans. A grain exposes a plain F# API record, a grainContract defines its identity and policies, and grainFor or journaledGrainFor supplies behavior.
Do I need a C# proxy or CodeGen project?
Section titled “Do I need a C# proxy or CodeGen project?”No. The functional runtime uses precompiled Orleans proxies from Orleans.FSharp.Abstractions. Your application writes the actor brand, API record, contract, and definition in F#.
How do I create a grain reference?
Section titled “How do I create a grain reference?”open System.Threading.Tasksopen Orleans.FSharp
type CounterActor = private CounterActor of unit
[<NoEquality; NoComparison>]type CounterApi = { increment: unit -> Task<int> }
let counterContract = grainContract<CounterActor, string, CounterApi> { grainType "counter" version 1 stringKey }
let increment (grainFactory: Orleans.IGrainFactory) = task { let api = FunctionalGrain.ref counterContract grainFactory "counter-1" return! api.increment () }The returned value has the exact API-record type.
Which Orleans versions are supported?
Section titled “Which Orleans versions are supported?”The current package range starts at Orleans 10.1.0 and is tested against both 10.1.0 and 10.3.1. A NuGet lower bound means older 10.0.x versions are not selected. See Orleans Compatibility for release-specific notes.
Does event sourcing support snapshots?
Section titled “Does event sourcing support snapshots?”Yes. journaledGrainFor supports Orleans log-consistency providers and typed custom storage. Snapshot policy can be configured globally and overridden per grain definition; the definition-level policy wins.
Do streams, broadcasts, timers, and reminders work on journaled grains?
Section titled “Do streams, broadcasts, timers, and reminders work on journaled grains?”Yes. Journaled definitions support onStream, onBroadcast, onTimer, and onReminder with the same functional hooks as ordinary definitions. Event state changes still go through raised and confirmed events.
Can a functional grain survive a rolling update and schema change?
Section titled “Can a functional grain survive a rolling update and schema change?”Transport versions participate in native Orleans routing, and the integration suite runs separate
N/N+1 silo binaries plus rollback. Durable compatibility is configured separately:
PersistentState.withSchema, journal stateSchema, and journal eventSchema provide typed
upcasters. New-schema writes still cannot be read by an older binary, so use a reader-first bridge
release when rollback must remain possible.
What stream-provider surface is covered?
Section titled “What stream-provider surface is covered?”Item and batch publish/subscribe, sequence-token resume, error/completion callbacks, durable
reattachment, and Orleans IStreamFilter data are exposed. Producer completion/error remains
provider-dependent; Orleans 10.3.1’s persistent producer reports those operations as not
implemented, and the wrapper preserves that behavior.
Are DurableGrain, Microsoft.Orleans.Journaling, and Durable Jobs included?
Section titled “Are DurableGrain, Microsoft.Orleans.Journaling, and Durable Jobs included?”Not in the current Orleans.FSharp 5.0.1 release. They are intentionally deferred; the journaled functional grain is built over Orleans log-consistency providers. Experimental journaling support can be isolated in a future opt-in subpackage instead of making the stable package depend on it.
Can C# call a functional grain?
Section titled “Can C# call a functional grain?”Yes. Declare a C# facade interface and bind it with
FunctionalGrainInterop.For<TFacade>(contract, factory, key). C# receives normal task-returning
methods and can consume streaming replies with await foreach.
How do F# actors appear in Orleans Dashboard?
Section titled “How do F# actors appear in Orleans Dashboard?”The Dashboard activation table displays the functional manifest type, for example FunctionalGrainMarker<MyApp+CounterActor>. The actor brand is visible; API-record fields are transported through the shared functional dispatch operation. See Dashboard for a runnable example and the exact current display.
How do I start a project?
Section titled “How do I start a project?”dotnet new install Orleans.FSharp.Templates@5.0.1dotnet new orleans-fsharp -n MyAppAlready generated with 5.0.0? Apply the one-line startup correction; updating the template package does not rewrite existing source.
This installs the published stable template. Contributors validating repository changes can
instead clone the repository and run dotnet new install ./orleans-fsharp/templates. Then follow
Getting Started and review the boundaries in
Release and Production Status.
Where is documentation for existing applications on the original API?
Section titled “Where is documentation for existing applications on the original API?”It is retained as an unsupported migration reference under the Legacy archive, separate from current guides. There is no new Legacy release line or security support.
Is it production-ready?
Section titled “Is it production-ready?”The library includes unit and live Orleans integration suites, dual-version CI coverage, wire-contract validation, persistence, transactions, event sourcing, streaming, reminders, timers, and production hosting helpers. Those checks do not certify every provider or workload. Review the verified boundaries in Release and Production Status, then validate storage providers, deployment topology, payload sizes, observability, and upgrade behavior against your own workload.