Docs / Guides

Quickstart

This walks through the smallest working setup: one process hosting Axon.Server, and a client enqueuing a job that runs on itself. In a real deployment the server and the job's implementation usually live in different microservices — that split is the whole point of Axon — but everything here works the same either way.

1. Install the packages

$ dotnet add package GoAxon.Server
$ dotnet add package GoAxon.Client

2. Register the server

AddAxonServer() registers the core scheduler — SignalR hub, job store, background processors — with no HTTP surface mapped yet. Chain .AddAxonDashboard() to also map the JSON API and the admin dashboard:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAxonServer()
    .AddAxonDashboard();

3. Register the client

Point the client at wherever Axon.Server is hosted. This opens the persistent SignalR/WebSocket connection jobs get dispatched over:

builder.Services.AddAxonClient(axonBaseUrl); // e.g. "https://localhost:7221"

4. Map the middleware

var app = builder.Build();

app.UseAxonServer();

app.Run();

This maps the SignalR hub, the /axon API/dashboard (if opted into above), and two unauthenticated health check endpoints — /axon/health/live and /axon/health/ready — for your orchestrator.

5. Enqueue a job

Inject IAxonClient and call a method on any plain class. Axon serializes the call as an expression tree, sends it to the server, and the server dispatches it back to a connected client for execution:

public class WeatherForecastController(IAxonClient axonClient) : ControllerBase
{
    [HttpGet]
    public async Task<IActionResult> Get()
    {
        var jobId = await axonClient.EnqueueAsync<MyClass>(x => x.WriteHelloWorld("Hello World"));
        return Ok(new { JobId = jobId });
    }
}

public class MyClass
{
    public void WriteHelloWorld(string message) => Console.WriteLine(message);
}

That's it — MyClass never needs to be referenced by Axon.Server. The server only ever sees its assembly name, type name, method name, and JSON-serialized arguments.