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.
Install
Section titled “Install”dotnet add package Kurrent.SurgeRequires .NET 10.0 or a subsequent version. That one package carries the client, the processors and the codecs.
Declare your messages
Section titled “Declare your messages”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:
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.
Produce: append and read
Section titled “Produce: append and read”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.
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:
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.
Consume: run a processor
Section titled “Consume: run a processor”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.
More examples
Section titled “More examples”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.