From EventStoreDB
Kurrent Surge is the successor to the EventStoreDB .NET client. This guide covers what changed, what keeps working, and the order to change things in.
Your esdb:// connection strings keep working. See Migration for the full scheme
table. Everything below is about packages, namespaces, and API shape.
Packages
Section titled “Packages”The old client shipped as four packages. Kurrent.Surge is one.
dotnet remove package EventStore.Client.Grpc.Streamsdotnet remove package EventStore.Client.Grpc.PersistentSubscriptionsdotnet remove package EventStore.Client.Grpc.ProjectionManagementdotnet remove package EventStore.Client.Grpc.Operations
dotnet add package Kurrent.SurgeKurrent.Surge carries streams, the schema registry, secondary indexes, connectors, and node
administration behind one KurrentClient.
Namespaces
Section titled “Namespaces”| Old | New |
|---|---|
EventStore.Client |
Kurrent.Surge.Client |
EventStore.Client.Streams |
Kurrent.Surge.Client.Streams |
// Oldusing EventStore.Client;
// Newusing Kurrent.Surge.Client;using Kurrent.Surge.Client.Streams;One client, five modules
Section titled “One client, five modules”The old client gave you a type per feature. Kurrent Surge gives you one client, and reaches features through module properties.
// Oldvar settings = EventStoreClientSettings.Create("esdb://admin:changeit@localhost:2113?tls=false");var client = new EventStoreClient(settings);
// Newawait using var client = KurrentClient.Create("kurrentdb://admin:changeit@localhost:2113?tls=false");Note the await using. IKurrentClient is IAsyncDisposable, not IDisposable.
| Module | Reached through | Covers |
|---|---|---|
| Streams | client.Streams |
Append, read, delete, tombstone, truncate, metadata |
| Registry | client.Registry |
Schema registry |
| Indexes | client.Indexes |
Secondary indexes |
| Connectors | client.Connectors |
Connector lifecycle |
| Admin | client.Admin |
Scavenge, shutdown, leader resignation, node priority |
// Oldawait client.AppendToStreamAsync("my-stream", StreamState.Any, events);
// Newawait client.Streams.AppendStream("my-stream", records, ExpectedStreamState.Any);Configuration
Section titled “Configuration”KurrentClientOptions replaces EventStoreClientSettings. It is a record, so with composes on top
of a parsed connection string.
// From a connection stringawait using var client = KurrentClient.Create("kurrentdb://admin:changeit@localhost:2113");
// With overridesawait using var client = KurrentClient.Create( "kurrentdb://admin:changeit@localhost:2113", opts => { opts.Resilience = KurrentClientResilienceOptions.HighAvailability; opts.LoggerFactory = loggerFactory; });
// From a parsed connection stringvar options = KurrentClientOptions.Parse("kurrentdb://admin:changeit@localhost:2113") with { Resilience = KurrentClientResilienceOptions.HighAvailability};Resilience presets: Default, NoResilience, FailFast, HighAvailability, CautiousWrite,
Subscription, RetryForever.
Security presets: Insecure, Tls, Password, MutualTls.
Records replace events
Section titled “Records replace events”EventData becomes AppendRecord. ResolvedEvent and RecordedEvent become Record.
// Oldvar eventData = new EventData( Uuid.NewUuid(), "OrderPlaced", JsonSerializer.SerializeToUtf8Bytes(new { OrderId = "123" }));
await client.AppendToStreamAsync("order-123", StreamState.Any, new[] { eventData });
// Newvar record = new AppendRecord { Stream = "order-123", Value = new { OrderId = "123" }};
var result = await client.Streams.AppendStream(record);You no longer serialize by hand. AppendRecord encodes as JSON by default, and the schema name comes
from your message catalog. See Catalogs.
Reads return an async sequence that interleaves records with checkpoints:
// Oldvar events = client.ReadStreamAsync(Direction.Forwards, "order-123", StreamPosition.Start);
await foreach (var resolvedEvent in events) Console.WriteLine(resolvedEvent.Event.EventType);
// Newawait foreach (var item in client.Streams.ReadStream("order-123")) { item.Switch( record => Console.WriteLine("{0} at revision {1}", record.TypeName, record.Revision), checkpoint => { });}The Async suffix is gone. The methods are still async, and return IAsyncEnumerable<ReadMessage>
or a Task.
Exceptions are typed
Section titled “Exceptions are typed”The old client threw WrongExpectedVersionException for concurrency conflicts. Kurrent Surge throws
a distinct type per failure, so you catch the case you actually handle.
// Oldcatch (WrongExpectedVersionException ex) { }
// Newcatch (StreamRevisionConflictException ex) { Console.WriteLine("Expected {0}, was {1}", ex.ExpectedRevision, ex.ActualRevision);}Also available: StreamNotFoundException, StreamAlreadyExistsException, StreamDeletedException,
StreamTombstonedException, LogPositionNotFoundException,
MaxAppendRecordSizeExceededException, MaxAppendTransactionSizeExceededException.
A read throws when you first iterate it, not when you call it. Wrap the await foreach, not the
call to ReadStream.
Dependency injection
Section titled “Dependency injection”// Oldservices.AddEventStoreClient("esdb://admin:changeit@localhost:2113?tls=false");
// Newservices.AddKurrentSurge(surge => surge .Connection("kurrentdb://admin:changeit@localhost:2113?tls=false"));Checklist
Section titled “Checklist”-
Packages. Remove all four
EventStore.Client.Grpc.*, and addKurrent.Surge. -
Usings.
EventStore.ClientbecomesKurrent.Surge.Client, plus the feature namespaces you use. -
Construction.
new EventStoreClient(settings)becomesKurrentClient.Create(connectionString), andusingbecomesawait using. -
Calls. Route through the module and drop the
Asyncsuffix:Old New client.AppendToStreamAsync(...)client.Streams.AppendStream(...)client.ReadStreamAsync(...)client.Streams.ReadStream(...)client.DeleteAsync(...)client.Streams.Delete(...)client.TombstoneAsync(...)client.Streams.Tombstone(...) -
Record types.
EventDatabecomesAppendRecord, andResolvedEventorRecordedEventbecomesRecord:Old New resolvedEvent.Event.EventTyperecord.TypeNameresolvedEvent.Event.OriginalEventNumberrecord.RevisionresolvedEvent.Event.Positionrecord.PositionresolvedEvent.OriginalPositionrecord.CheckpointPosition -
Concurrency.
StreamRevisionbecomesRevision, andStreamStatebecomesExpectedStreamState.Revisionconverts implicitly, soRevision.From(4)passes anywhereExpectedStreamStateis wanted. -
Exceptions. Replace
WrongExpectedVersionExceptionwithStreamRevisionConflictException. -
Registration.
AddEventStoreClientbecomesAddKurrentSurge, which takes a scope rather than a connection string. See Wiring Up Surge. -
Declare your message types. This step has no equivalent in the old client and is the one that will bite you. Kurrent Surge does not infer schema names, so an append of an undeclared type throws. See Catalogs.
-
Build, then run your tests. The compiler finds the remaining call sites.
-
Connection strings, whenever you like.
esdb://keeps working indefinitely.
Breaking changes
Section titled “Breaking changes”| Area | Old | Kurrent Surge |
|---|---|---|
| Package | Four EventStore.Client.Grpc.* |
One Kurrent.Surge |
| Namespace | EventStore.Client |
Kurrent.Surge.Client |
| Client type | EventStoreClient |
KurrentClient |
| Construction | new EventStoreClient(settings) |
KurrentClient.Create(...) |
| Settings | EventStoreClientSettings |
KurrentClientOptions |
| Feature access | Top-level methods | Module properties |
| Append model | EventData |
AppendRecord |
| Read model | ResolvedEvent or RecordedEvent |
Record, with Checkpoint interleaved |
| Link resolution | resolveLinkTos: true |
Automatic on a stream read, never on $all |
| Stream state | StreamState |
ExpectedStreamState |
| Revision | StreamRevision |
Revision |
| Method names | *Async suffix |
No suffix |
| Disposal | IDisposable |
IAsyncDisposable |
| Schema names | Inferred from the event type string | Declared in a catalog |