Akka.Hosting Actor Patterns

When to Use This Skill

Use this skill when:

• Building entity actors that represent domain objects (users, orders, invoices, etc.)
• Need actors that work in both unit tests (no clustering) and production (cluster sharding)
• Setting up scheduled tasks with akka-reminders
• Registering actors with Akka.Hosting extension methods
• Creating reusable actor configuration patterns

Core Principles

1. Execution Mode Abstraction - Same actor code runs locally (tests) or clustered (production)
2. GenericChildPerEntityParent for Local - Mimics sharding semantics without cluster overhead
3. Message Extractors for Routing - Reuse Akka.Cluster.Sharding's IMessageExtractor interface
4. Akka.Hosting Extension Methods - Fluent configuration that composes well
5. ITimeProvider for Testability - Use ActorSystem.Scheduler instead of DateTime.Now

Execution Modes

Define an enum to control actor behavior:

/// <summary>
/// Determines how Akka.NET should be configured
/// </summary>
public enum AkkaExecutionMode
{
    /// <summary>
    /// Pure local actor system - no remoting, no clustering.
    /// Use GenericChildPerEntityParent instead of ShardRegion.
    /// Ideal for unit tests and simple scenarios.
    /// </summary>
    LocalTest,

    /// <summary>
    /// Full clustering with ShardRegion.
    /// Use for integration testing and production.
    /// </summary>
    Clustered
}

GenericChildPerEntityParent

A lightweight parent actor that routes messages to child entities, mimicking cluster sharding semantics without requiring a cluster:

using Akka.Actor;
using Akka.Cluster.Sharding;