Instruction file imported from Gibbs-Morris/mississippi (.github/instructions/orleans.instructions.md). Copyright stays with the author.

Orleans POCO Grains

Governing thought: Use Orleans 7+ POCO grains with IGrainBase, constructor injection, and extension methods—never inherit from Grain.

Drift check: Review Orleans settings/packages in Directory.Build.props before editing grains.

Rules (RFC 2119)

• Grains MUST implement IGrainBase (with public IGrainContext GrainContext { get; }) and MUST NOT inherit from Grain; concrete grains MUST be sealed. Why: Follows Orleans POCO guidance and prevents unintended inheritance.
• All dependencies, including IGrainContext, MUST be injected via constructor and stored with the DI get-only property pattern; private readonly fields for DI MUST NOT be used. Why: Aligns with shared guardrails and testability.
• using Orleans.Runtime; MUST be included and Orleans extension methods MUST be called with this. qualification. Why: Ensures access to grain helpers.
• Grain interfaces MUST be public only when external callers need them; otherwise keep internal. Why: Controls API surface.
• Existing grains inheriting from Grain SHOULD be migrated to POCO; abstract classes inheriting IGrainBase MUST end with Base, and migrations SHOULD be tracked if deferred. Why: Keeps patterns consistent and discoverable.
• When converting from Grain<TState>, developers SHOULD inject IPersistentState<TState> instead. Why: POCO pattern handles state via DI.

Scope and Audience

Developers implementing Orleans grains and grain interfaces.

At-a-Glance Quick-Start

• Implement IGrainBase; add GrainContext property; inject dependencies in the constructor with get-only properties.
• Add using Orleans.Runtime; and call helpers as this.GetPrimaryKeyString(), this.DeactivateOnIdle(), etc.
• Keep concrete grains sealed; limit public interfaces to external needs.
• Track migrations for legacy Grain inheritance in .scratchpad/tasks if not fixed immediately.

Core Principles

• Composition over inheritance; POCO grains are easier to test and refactor.
• Explicit DI and extension methods keep behavior clear and analyzer-friendly.

References

• Shared guardrails: .github/instructions/shared-policies.instructions.md
• Serialization: .github/instructions/orleans-serialization.instructions.md