Files

Joseph Doherty de636b908b Add Akka.NET reference documentation

Notes and documentation covering actors, remoting, clustering, persistence,
streams, serialization, hosting, testing, and best practices for the Akka.NET
framework used throughout the ScadaLink system.

2026-03-16 09:08:17 -04:00

11 KiB

Raw Blame History

Akka.NET Components Reference

This document catalogs the major components (modules/libraries) of the Akka.NET framework, along with a brief description and a link to the official documentation for each.

Core Components

1. Actors (Akka — The Core Library)

The foundational building block of Akka.NET. Actors encapsulate state and behavior, communicate exclusively through asynchronous message passing, and form supervision hierarchies for fault tolerance. The core library includes the ActorSystem, Props, IActorRef, mailboxes, dispatchers, routers, FSM (Finite State Machine), and the supervision/monitoring model.

NuGet Package: Akka
Documentation: https://getakka.net/articles/intro/what-is-akka.html
Concepts — Actor References: https://getakka.net/articles/concepts/actors.html
Supervision & Monitoring: https://getakka.net/articles/concepts/supervision.html

2. Remoting (Akka.Remote)

Enables transparent communication between actor systems running on different hosts or processes. Messages are serialized and sent over the network; remote and local message sends use the same API. Remoting is the transport layer upon which Clustering is built.

NuGet Package: Akka.Remote
Documentation: https://getakka.net/articles/remoting/index.html
Configuration Reference: https://getakka.net/articles/configuration/modules/akka.remote.html

3. Cluster (Akka.Cluster)

Organizes multiple actor systems into a membership-based "meta-system" with failure detection, member lifecycle management, role assignment, and split-brain resolution. In most real-world applications, Cluster is used instead of raw Remoting.

NuGet Package: Akka.Cluster
Documentation: https://getakka.net/articles/clustering/cluster-overview.html
Configuration Reference: https://getakka.net/articles/configuration/modules/akka.cluster.html

4. Cluster Sharding (Akka.Cluster.Sharding)

Distributes a large set of stateful entities (actors) across cluster members. Entities are addressed by an identifier and are automatically balanced, migrated on failure, and guaranteed to be unique across the cluster. Typically paired with Persistence.

NuGet Package: Akka.Cluster.Sharding
Documentation: https://getakka.net/articles/clustering/cluster-sharding.html

5. Cluster Singleton (Akka.Cluster.Tools)

Ensures that exactly one instance of a particular actor exists across the entire cluster at any given time. If the hosting node goes down, the singleton is automatically migrated to another node.

NuGet Package: Akka.Cluster.Tools
Documentation: https://getakka.net/articles/clustering/cluster-singleton.html

Provides a distributed publish-subscribe mechanism within a cluster. Messages can be broadcast to all subscribers of a topic or sent to a single interested party. Part of the Akka.Cluster.Tools package alongside Cluster Singleton.

NuGet Package: Akka.Cluster.Tools
Documentation: https://getakka.net/articles/clustering/distributed-publish-subscribe.html

7. Cluster Metrics (Akka.Cluster.Metrics)

Collects and publishes node-level resource metrics (CPU, memory) across the cluster. Useful for adaptive load balancing and monitoring.

NuGet Package: Akka.Cluster.Metrics
Documentation: https://getakka.net/articles/clustering/cluster-metrics.html

8. Persistence (Akka.Persistence)

Enables actors to persist their state as a sequence of events (event sourcing) or snapshots. On restart or migration, the actor replays its event journal to recover state. Supports pluggable journal and snapshot store backends (SQL Server, PostgreSQL, SQLite, MongoDB, etc.).

NuGet Package: Akka.Persistence
Documentation: https://getakka.net/articles/persistence/architecture.html
Configuration Reference: https://getakka.net/articles/configuration/modules/akka.persistence.html
Persistence Query (CQRS Projections): https://getakka.net/articles/persistence/persistence-query.html

9. Distributed Data (Akka.DistributedData)

Shares data across cluster nodes using Conflict-Free Replicated Data Types (CRDTs). Supports reads and writes even during network partitions, with eventual consistency guarantees and automatic conflict resolution.

NuGet Package: Akka.DistributedData
Documentation: https://getakka.net/articles/clustering/distributed-data.html

10. Streams (Akka.Streams)

A higher-level abstraction on top of actors for building reactive, back-pressured stream processing pipelines. Implements the Reactive Streams standard. Provides composable building blocks: Source, Flow, Sink, and Graph DSL.

NuGet Package: Akka.Streams
Documentation: https://getakka.net/articles/streams/introduction.html
Modularity & Composition: https://getakka.net/articles/streams/modularitycomposition.html

Hosting & Integration

11. Akka.Hosting

The recommended modern integration layer for Akka.NET with the Microsoft.Extensions.* ecosystem (Hosting, DependencyInjection, Configuration, Logging). Provides HOCON-less, code-first configuration and an ActorRegistry for injecting actor references into ASP.NET Core, SignalR, gRPC, and other DI-based services.

NuGet Package: Akka.Hosting
GitHub / Documentation: https://github.com/akkadotnet/Akka.Hosting
Sub-packages:
- Akka.Remote.Hosting — Akka.Remote configuration via Hosting
- Akka.Cluster.Hosting — Akka.Cluster, Sharding, and Tools configuration via Hosting
- Akka.Persistence.Hosting — Persistence configuration via Hosting

12. Akka.DependencyInjection

Integrates Microsoft.Extensions.DependencyInjection (or other DI containers) directly into actor construction, allowing actors to receive injected services through their constructors.

NuGet Package: Akka.DependencyInjection
Documentation: https://getakka.net/articles/actors/dependency-injection.html

Discovery & Management

13. Akka.Discovery

Provides a pluggable service discovery API for dynamically locating cluster nodes in cloud and containerized environments. Ships with a built-in config-based discovery method and supports plugins for AWS, Azure, Kubernetes, and more.

NuGet Package: Akka.Discovery (core); provider-specific packages (e.g. Akka.Discovery.Azure, Akka.Discovery.AwsApi, Akka.Discovery.KubernetesApi)
Documentation: https://getakka.net/articles/discovery/index.html

14. Akka.Management

A toolkit for managing and bootstrapping Akka.NET clusters in dynamic environments. Exposes HTTP endpoints for cluster coordination and works with Akka.Discovery to enable safe, automated cluster formation via Cluster Bootstrap (replacing static seed nodes).

NuGet Package: Akka.Management
Documentation: https://getakka.net/articles/discovery/akka-management.html
GitHub: https://github.com/akkadotnet/Akka.Management

15. Akka.Coordination

Provides lease-based distributed locking primitives used by Split Brain Resolver, Cluster Sharding, and Cluster Singleton to prevent split-brain scenarios. Backend implementations include Azure Blob Storage (Akka.Coordination.Azure).

NuGet Package: Akka.Coordination.Azure
Documentation (Azure Lease): https://github.com/akkadotnet/Akka.Management (see Coordination section)

Testing

16. Akka.TestKit

The base testing framework for Akka.NET actors. Provides TestProbe, TestActorRef, EventFilter, and other utilities for unit and integration testing of actor-based systems. Requires a test-framework-specific adapter package.

NuGet Package: Akka.TestKit (base), Akka.TestKit.Xunit2, Akka.TestKit.NUnit, Akka.TestKit.MSTest
Documentation: https://getakka.net/articles/actors/testing-actor-systems.html

17. Akka.Hosting.TestKit

An integration testing toolkit built on top of Akka.Hosting and xUnit. Provides a TestKit base class that spins up a full Microsoft.Extensions.Hosting environment with DI, logging, and Akka.NET — ideal for testing actors alongside other services.

NuGet Package: Akka.Hosting.TestKit
NuGet Page: https://www.nuget.org/packages/Akka.Hosting.TestKit

18. Akka.MultiNodeTestRunner

Infrastructure for running distributed, multi-node integration tests across multiple actor systems. Used to validate cluster behavior, split-brain scenarios, and network partition handling.

GitHub: https://github.com/akkadotnet/Akka.MultiNodeTestRunner

Networking

19. Akka.IO

Low-level, actor-based TCP and UDP networking built into the core Akka library. Provides non-blocking I/O through an actor API rather than traditional socket programming.

Part of the core Akka NuGet package
Documentation (TCP): https://getakka.net/articles/networking/io.html

Serialization & Configuration

20. Serialization

Akka.NET includes a pluggable serialization system used for message passing (both local and remote). The default serializer is JSON-based; high-performance alternatives include Hyperion and custom Serializer implementations. Serialization is critical for Remoting, Persistence, and Cluster Sharding.

Part of the core Akka NuGet package
Documentation: https://getakka.net/articles/networking/serialization.html

21. HOCON Configuration

Akka.NET uses HOCON (Human-Optimized Config Object Notation) as its primary configuration format. HOCON supports includes, substitutions, and hierarchical keys. With Akka.Hosting, HOCON can be replaced entirely by code-first configuration.

Documentation: https://getakka.net/articles/configuration/hocon.html
Module Configs: https://getakka.net/articles/configuration/modules/akka.html

Persistence Providers (Selected)

Akka.Persistence supports pluggable backends. Some notable provider packages:

Provider	NuGet Package	Documentation / GitHub
SQL (Linq2Db — SQL Server, PostgreSQL, SQLite, MySQL, Oracle)	`Akka.Persistence.Sql`	https://github.com/akkadotnet/Akka.Persistence.Sql
MongoDB	`Akka.Persistence.MongoDb`	https://github.com/akkadotnet/Akka.Persistence.MongoDB
Azure (Table Storage / Blob Storage)	`Akka.Persistence.Azure`	https://github.com/petabridge/Akka.Persistence.Azure

Logging Integrations

Logger	NuGet Package	GitHub
Serilog	`Akka.Logger.Serilog`	https://github.com/akkadotnet/Akka.Logger.Serilog
NLog	`Akka.Logger.NLog`	https://github.com/akkadotnet/Akka.Logger.NLog

Additional Resources

Official Documentation Home: https://getakka.net/
GitHub Organization: https://github.com/akkadotnet
Modules Overview: https://getakka.net/articles/intro/modules.html
Bootcamp (Learn Akka.NET): https://learnakka.net/
Example Projects: https://getakka.net/articles/examples.html
Community Discord: https://discord.gg/GSCfPwhbWP
Petabridge (Commercial Support): https://petabridge.com/

11 KiB Raw Blame History