💬 Join our Slack channel

Proto.Actor

Ultra-fast, distributed, cross-platform actors.

Bootcamp Training

https://github.com/AsynkronIT/protoactor-bootcamp

Stats

Installing

Using NuGet Package Manager Console:

PM> Install-Package Proto.Actor

Source code

This is the .NET repository for Proto Actor.

Other implementations:

• Go: https://github.com/AsynkronIT/protoactor-go

Documentation

Additional root-level documents provide deeper insights into the project:

• CODEBASE_OVERVIEW.md – overview of the repository structure and key concepts.
• CLUSTER_MEMBERSHIP_GOSSIP.md – explains how cluster membership is detected and propagated via gossip.
• EVENTSTREAM_EVENTS.md – lists key EventStream events and their publishers/subscribers.
• SECURITY.md – security policy and supported versions.
• Terminology.md – definitions of common Proto.Actor terms.

Test coverage

You can capture code coverage directly when running the test projects. The .NET SDK ships an XPlat Code Coverage data collector that works across platforms, so you do not need any third-party tooling for the basic workflow.

Quick coverage run

Run any test project with coverage enabled by passing the CollectCoverage property:

dotnet test /p:CollectCoverage=true

This uses the built-in collector and writes coverage data under the TestResults directory for the invocation.

Using coverlet.collector

For richer reporting support you can opt into the coverlet.collector package. Add it to the test project you want to analyze:

dotnet add package coverlet.collector

Then request coverage when running the tests:

dotnet test --collect:"XPlat Code Coverage"

This produces a .coverage file under TestResults/... that can be converted into other formats.

Alternative output formats

You can ask the collector to emit other formats such as Cobertura, lcov, or OpenCover. For example, to produce an lcov report:

dotnet test --collect:"XPlat Code Coverage" -- DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=lcov

HTML reports

Feed the generated lcov or cobertura files into tools like ReportGenerator to build browsable HTML output. Install the global tool and point it at your coverage reports:

dotnet tool install -g dotnet-reportgenerator-globaltool
reportgenerator -reports:**/coverage.cobertura.xml -targetdir:coveragereport

Open the files in the coveragereport directory to inspect the results.

Design principles

Minimalistic API - The API should be small and easy to use. Avoid enterprisey containers and configurations.

Build on existing technologies - There are already a lot of great technologies for e.g. networking and clustering. Build on those instead of reinventing them. E.g. gRPC streams for networking, Consul for clustering.

Pass data, not objects - Serialization is an explicit concern - don't try to hide it. Protobuf all the way.

Be fast - Do not trade performance for magic API trickery.

Getting started

The best place currently for learning how to use Proto.Actor is the examples. Documentation and guidance is under way, but not yet complete, and can be found on the website.

Hello world

Define a message type:

internal record Hello(string Who);

Define an actor:

internal class HelloActor : IActor
{
    public Task ReceiveAsync(IContext context)
    {
        var msg = context.Message;
        if (msg is Hello r)
        {
            Console.WriteLine($"Hello {r.Who}");
        }
        return Task.CompletedTask;
    }
}

Spawn it and send a message to it:

var system = new ActorSystem();
var context = system.Root;
var props = Props.FromProducer(() => new HelloActor());
var pid = context.Spawn(props);

context.Send(pid, new Hello("Alex"));

You should see the output Hello Alex.

Sample application

https://github.com/asynkron/realtimemap-dotnet

Contributors

Made with contributors-img.

Partners, Sponsors, and Contributor Companies

Name	Role
Asynkron AB	Founder and owner of Proto.Actor
Helleborg AS	Core contributor team
Ubiquitous AS	Core contributor team
Ahoy Games	Core contributor team
Etteplan	Contributing tutorials, documentation