akka-net-best-practices

Akka.NET Best Practices

When to Use This Skill

Use this skill when:

• Designing actor communication patterns
• Deciding between EventStream and DistributedPubSub
• Implementing error handling in actors
• Understanding supervision strategies
• Choosing between Props patterns and DependencyResolver
• Designing work distribution across nodes
• Creating testable actor systems that can run with or without cluster infrastructure
• Abstracting over Cluster Sharding for local testing scenarios

Reference Files

• work-distribution-patterns.md: Database queues, Akka.Streams throttling, outbox pattern
• cluster-local-abstractions.md: GenericChildPerEntityParent, IPubSubMediator, execution mode wiring
• async-cancellation-patterns.md: Actor-scoped CancellationToken, linked CTS, timeout handling

1. EventStream vs DistributedPubSub

Critical: EventStream is LOCAL ONLY

Context.System.EventStream is local to a single ActorSystem process. It does NOT work across cluster nodes.

// BAD: This only works on a single server
// When you add a second server, subscribers on server 2 won't receive events from server 1
Context.System.EventStream.Subscribe(Self, typeof(PostCreated));
Context.System.EventStream.Publish(new PostCreated(postId, authorId));

When EventStream is appropriate:

• Logging and diagnostics within a single process
• Local event bus for truly single-process applications
• Development/testing scenarios

Use DistributedPubSub for Multi-Node

For events that must reach actors across multiple cluster nodes, use Akka.Cluster.Tools.PublishSubscribe:

using Akka.Cluster.Tools.PublishSubscribe;

public class TimelineUpdatePublisher : ReceiveActor
{
    private readonly IActorRef _mediator;

    public TimelineUpdatePublisher()
    {
        // Get the DistributedPubSub mediator
        _mediator = DistributedPubSub.Get(Context.System).Mediator;

        Receive<PublishTimelineUpdate>(msg =>
        {
            // Publish to a topic - reaches all subscribers across all nodes
            _mediator.Tell(new Publish($"timeline:{msg.UserId}", msg.Update));
        });
    }
}