akka-hosting-actor-patterns

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;

/// <summary>
/// A generic "child per entity" parent actor.
/// </summary>
/// <remarks>
/// Reuses Akka.Cluster.Sharding's IMessageExtractor for consistent routing.
/// Ideal for unit tests where clustering overhead is unnecessary.
/// </remarks>
public sealed class GenericChildPerEntityParent : ReceiveActor
{
    public static Props CreateProps(
        IMessageExtractor extractor,
        Func<string, Props> propsFactory)
    {
        return Props.Create(() =>
            new GenericChildPerEntityParent(extractor, propsFactory));
    }

    private readonly IMessageExtractor _extractor;
    private readonly Func<string, Props> _propsFactory;

    public GenericChildPerEntityParent(
        IMessageExtractor extractor,
        Func<string, Props> propsFactory)
    {
        _extractor = extractor;
        _propsFactory = propsFactory;

        ReceiveAny(message =>
        {
            var entityId = _extractor.EntityId(message);
            if (entityId is null) return;

            // Get existing child or create new one
            Context.Child(entityId)
                .GetOrElse(() => Context.ActorOf(_propsFactory(entityId), entityId))
                .Forward(_extractor.EntityMessage(message));
        });
    }
}