Skip to content

Getting Started

Two roles, two first programs. Install and declare your messages either way, then take the path that matches what you are building.

You are You want Go to
A producer Get events into KurrentDB and read them back Append and read
A consumer React to events as they arrive, continuously Run a processor

For what Surge is and how it is designed, read What is Kurrent Surge first.

Terminal window
dotnet add package Kurrent.Surge

Requires .NET 10.0 or a subsequent version. That one package carries the client, the processors and the codecs.

Both paths need this. The SDK maps a CLR type to a schema name through a catalog. Declare one for the namespace that holds your events and the client picks it up:

Orders.Events.cs
using Kurrent.Surge.Schema.Catalogs;
[assembly: MessageCatalog("Orders.Events", AlwaysActive = true)]
namespace Orders.Events {
public record OrderPlaced(string OrderId, string Customer, int Quantity);
}

Without a catalog the client cannot resolve a schema name for your type, and the append is rejected. See Catalogs for the other ways to declare one.

A producer talks to KurrentDB through KurrentClient. AddKurrentSurge registers one for injection. One client reaches all five modules, and streams is the one you want first.

Program.cs
using Kurrent.Surge;
using Kurrent.Surge.Client;
using Kurrent.Surge.Client.Streams;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddKurrentSurge(surge =>
// tls=false is the local development mode. Production drops it: /kurrent-surge/client/security/
surge.Connection("kurrentdb://localhost:2113?tls=false"));
using var host = builder.Build();
var client = host.Services.GetRequiredService<KurrentClient>();
var records = new[] { AppendRecord.Create(new OrderPlaced("ORD-001", "Alice", 3)) };
var result = await client.Streams.AppendStream("order-001", records, ExpectedStreamState.NoStream);
Console.WriteLine($"Wrote revision {result.Revision}.");

Reading it back is a lazy enumeration, so nothing buffers the whole stream:

Program.cs
await foreach (var message in client.Streams.ReadStream("order-001")) {
if (message.Value is Record record)
Console.WriteLine(record.Value);
}

The whole program runs: examples/streams/Streams.QuickStart is 38 lines that append three order events and read them back, with the output it produces.

Building a client directly with KurrentClient.Create is also supported, for scenarios the container does not own. See Configuring the Client.

Next: Append for concurrency control, Read for the live tail, Configuring the Client for the other four modules.

Reading a stream by hand suits a query. A processor suits everything else. It owns the subscription, the checkpoints, the retries and the batching, and leaves you one method.

using Kurrent.Surge.Processors;
public sealed class OrderNotifier : IRecordProcessor {
public ValueTask ProcessRecord(ProcessRecordContext context) {
if (context.Record.Value is OrderPlaced placed)
Console.WriteLine($"Order {placed.OrderId} placed by {placed.Customer}");
return ValueTask.CompletedTask;
}
}

To run the processor, give its type to AddProcessor<T> on the host builder:

using Kurrent.Surge;
using Kurrent.Surge.Client.Streams;
using Kurrent.Surge.Processors;
using Microsoft.Extensions.Hosting;
var builder = Host.CreateApplicationBuilder(args);
builder.AddKurrentSurge(surge => surge.AddProcessor<OrderNotifier>(options => {
// tls=false is the local development mode. Production drops it: /kurrent-surge/client/security/
options.Connection("kurrentdb://localhost:2113?tls=false");
options.Subscription.Filter = RecordFilter.ByStream("order-001");
}));
await builder.Build().RunAsync();

AddProcessor registers OrderNotifier in the container for you. Without a filter the processor reads every stream. SIGINT and SIGTERM stop the host, and the processor commits what it has handled before it exits, so a container stop drains rather than kills.

The whole program runs: examples/processors/Processor.QuickStart is one file with inline handlers. Processor.WordCount seeds a stream and counts words across it. Processor.AspNetMinimal hosts one in an ASP.NET Core application.

Next: Running a Processor, Writing a Processor, Checkpointing, Error Handling.

Eighteen runnable projects live in examples/, covering fraud detection, IoT thresholds, leaderboards, stream-table joins, Postgres and Redis persistence, Kafka connectors and the schema registry. Sixteen carry a README, and each project runs with dotnet run.

To connect to a cluster, or to configure TLS, discovery or keepalive, see the Connection String Reference.