Microsoft Orleans grain: Should polymorphism be achieved at the grain or grain stat level?

Hi @Michał Śmiechowicz ,

Thanks for reaching out.

Regarding your concern, it really comes down to where the differences in your system actually live - in behavior or just in data.

If your different types (A, B, C) have different logic or behavior, then it’s better to model that at the grain level using interfaces like IGrainC : IGrainB : IGrainA. In Microsoft Orleans, grains are meant to encapsulate behavior, so this approach keeps things clean and aligned with how Orleans is designed. Each grain type can implement its own logic without needing a lot of conditional checks.

You can find more details here: https://learn.microsoft.com/en-us/dotnet/orleans/grains/

On the other hand, if the differences are mostly about data shape or stored state, and the behavior is largely the same, then using a shared grain with polymorphic state (e.g. classC : classB : classA with IPersistentState) can work well. This keeps the grain surface simpler, but you may end up adding type checks or branching logic inside the grain if behavior starts to diverge.

More on grain persistence and state: https://learn.microsoft.com/en-us/dotnet/orleans/grains/grain-persistence/

A good rule of thumb is:

• Use grain/interface inheritance when behavior differs
• Use state inheritance when only the data differs

If you’re unsure, it’s usually safer to lean toward grain-level polymorphism, because it avoids mixing multiple behaviors into a single grain and keeps things easier to maintain as your system grows.

You might also find the general design guidance helpful: https://learn.microsoft.com/en-us/dotnet/orleans/resources/best-practices/

Hope this helps! If my answer was helpful, I would greatly appreciate it if you could follow the instructions here so others with the same problem can benefit as well.

In Orleans, polymorphism is typically modeled at the grain interface and state type level, but with some clear constraints.

Key points from the Orleans model in the context:

1. Grain identity and behavior are separate from storage
   Grains are defined by their identity and behavior (interfaces such as IGrainWithGuidKey, IGrainWithStringKey, etc.) and can have volatile or persistent state:
   • Grain identity is defined via interfaces like IGrainWithGuidKey, IGrainWithIntegerKey, IGrainWithStringKey, etc. b55049ee-d13e-c519-6cc9-0e1e129f4604-004
   • State can be volatile or persisted using grain persistence APIs.
2. Preferred persistence model is IPersistentState<TState>
Grain<TGrainState> is considered legacy for adding storage to a grain. The recommended approach is IPersistentState<TState>:
   • Grain<TGrainState> is legacy; use IPersistentState<TState> instead. af443b67-9a4f-e58c-e82f-055d30008b23-008
   • IPersistentState<TState> gives a strongly typed state object and explicit ReadStateAsync, WriteStateAsync, ClearStateAsync semantics. 9f8bbdb8-faed-ccbc-66b1-f3a5de94f7f9-005
3. One storage provider per grain/state declaration
   A grain (or a PersistentStateAttribute-decorated state) is associated with a single storage provider instance:
   • [StorageProvider(ProviderName = "name")] associates a grain class with a particular provider. 9f8bbdb8-faed-ccbc-66b1-f3a5de94f7f9-005
   • A PersistentStateAttribute-decorated class can only be associated with one storage provider. 9f8bbdb8-faed-ccbc-66b1-f3a5de94f7f9-005
4. Serialization supports polymorphic state types
   Orleans’ serialization framework supports dynamic types and arbitrary polymorphism:
   • If an interface expects a base type (e.g., IDictionary) and a derived type is passed (e.g., SortedDictionary), the actual derived type is preserved across calls. cea5c9e0-8887-9e61-c735-27ed81d6cf37-020
   • The same serialization system is used for grain persistent state objects.

Given these points, for the specific design choice:

• Using interface inheritance for grains (IGrainC : IGrainB : IGrainA) is a good way to express behavioral polymorphism (shared methods, contracts, and identity semantics). This is how grain behavior is typically modeled.
• For state polymorphism, using a common base state type (e.g., BaseState) with derived types (StateA, StateB, StateC) and a single IPersistentState<BaseState> is compatible with Orleans’ serialization model, which supports polymorphism.
• The concern about multiple [PersistentState("a"|"b"|"c", "mongodb")] names is valid: each named state is bound to a specific storage configuration. Best practice is to keep the number of distinct storage names minimal and model variation in the state schema rather than multiplying storage names unless there is a clear operational reason.

In practice, a common pattern is:

• Define a base grain interface for shared behavior and derive more specific interfaces from it.
• Use one state field per grain (via IPersistentState<TState> or Grain<TState> if legacy) with a base state type and derived state types if polymorphism in data is needed.
• Keep storage configuration simple (few provider names, few state names) and let the state type hierarchy and Orleans serialization handle polymorphism.

This aligns with the guidance that:

• Grain persistence is about a strongly typed state object and explicit read/write operations. 9f8bbdb8-faed-ccbc-66b1-f3a5de94f7f9-005
• Serialization is designed to support polymorphic types for state and messages. cea5c9e0-8887-9e61-c735-27ed81d6cf37-020

So, modeling polymorphism primarily in the state hierarchy (with a single IPersistentState<BaseState> per grain) combined with interface inheritance for behavior is consistent with Orleans best practices and avoids proliferation of separate persistent state names like "a", "b", and "c" unless there is a strong configuration or operational need.

References:

• Grain persistence
• Best practices in Orleans
• Serialization in Orleans
• Microsoft Orleans
• Grain<TGrainState> Class
• Grain lifecycle overview