Overview (.NET API)
This wiki is no longer maintained and should not be used. Read the Event Store docs at docs.geteventstore.com.
The latest version of the page you are currently viewing is available here.
#.NET Client API - Overview
The .NET Client API communicates with the Event Store using over TCP, using length-prefixed serialized protocol buffers. The API allows for reading and writing operations, as well as for subscriptions to individual event streams or all events written.
##EventStoreConnection
The EventStoreConnection class is responsible for maintaining a full-duplex connection between the client and the event store server. EventStoreConnection is thread-safe, and it is recommended that only one instance per application is created.
All operations are handled fully asynchronously, returning either a Task or a Task<T>. There are versions of each of these methods which can be used in a synchronous manner, however they simply call .Wait() on the asynchronous version.
To get maximum performance from the connection, it is recommended that it be used asynchronously.
###Creating a connection
A new connection can be created using the following static methods on the EventStoreConnection class:
public static EventStoreConnection Create()public static EventStoreConnection Create(ConnectionSettings settings)
Before use, the instance must be connected to a server using one of:
public void Connect(IPEndPoint tcpEndPoint)public Task ConnectAsync(IPEndPoint tcpEndPoint)
In both cases, an IPEndPoint is passed as a parameter in order to specify the IP address and port of the server.
###ConnectionSettings
The settings for the EventStoreConnection are specified via a builder.
| Builder Method | Description |
|---|---|
.DoNotLog |
Configures the connection not to output log messages. This is the default. |
.UseCustomLogger(ILogger logger) |
Configures the connection to output log messages to the given instance of ILogger. |
.UseConsoleLogger() |
Configures the connection to output log messages to the console. |
.UseDebugLogger() |
Configures the connection to output log messages to the listeners configured on System.Diagnostics.Debug. |
.EnableVerboseLogging() |
Turns on verbose internal logging. Mostly useful for debugging the EventStoreConnection. |
.DisableVerboseLogging() |
Turns off verbose internal logic logging. |
.LimitOperationsQueueTo(int limit) |
Sets the limit for number of queued operations |
.LimitConcurrentOperationsTo(int limit) |
Limits the number of concurrent operations that this connection can have |
.LimitAttemptsForOperationTo(int limit) |
Limits the number of operation attempts. This limit includes the initial attempt. |
.LimitRetriesForOperationTo(int limit) |
Limits the number of operation retries. |
.KeepRetrying() |
Allows infinite operation retry attempts |
.LimitReconnectionsTo(int limit) |
Limits the number of reconnections this connection can try to make. |
.KeepReconnecting() |
Allows infinite reconnection attempts. |
.EnableOperationsForwarding() |
Enables the forwarding of operations in the Event Store (only affects cluster version) |
.DisableOperationsForwarding() |
Disables the forwarding operations in the Event Store (only affects cluster version) |
.SetReconnectionDelayTo(TimeSpan reconnectionDelay) |
Sets the delay between reconnection attempts |
.SetOperationTimeoutTo(TimeSpan operationTimeout) |
Sets the operation timeout duration |
.SetTimeoutCheckPeriodTo(TimeSpan timeoutCheckPeriod) |
Sets how often timeouts should be checked for. |
.OnErrorOccurred(Action handler) |
Sets callback for internal connection errors. |
.OnClosed(Action handler) |
Sets callback for when connection is closed. |
.OnConnected(Action handler) |
Sets callback for when connection is established. |
.OnDisconnected(Action handler) |
Sets callback for when connection is disconnected. |
.OnReconnecting(Action handler) |
Sets callback for when reconnection attempt is made. |