Writing Events (.NET API)

 

 

 

DOCS HAVE MOVED

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.

 

 

 

The client API can be used to write one or more events to a stream atomically. This can be done either by appending the events to the stream in one operation, or by starting a transaction on the stream, writing events in one or more operations in that transaction, and then committing the transaction.

An optimistic concurrency check can be made during the write by specifying the version at which the stream is expected to be currently. Identical write operations are idempotent if the optimistic concurrency check is not disabled. More information on optimistic concurrency and idempotence can be found here.

##Methods

###Appending to a stream in a single write

• Task AppendToStreamAsync(string stream, int expectedVersion, IEnumerable events)

• Task AppendToStreamAsync(string stream, int expectedVersion, params EventData[] events)

• void AppendToStream(string stream, int expectedVersion, IEnumerable events)

• void AppendToStream(string stream, int expectedVersion, params EventData[] events)

###Using a transaction to append to a stream across multiple writes

####On EventStoreConnection:

• Task<EventStoreTransaction> StartTransactionAsync(string stream, int expectedVersion)

• EventStoreTransaction StartTransaction(string stream, int expectedVersion)

• EventStoreTransaction ContinueTransaction(long transactionId)

####On EventStoreTransaction:

• Task WriteAsync(IEnumerable<EventData> events)

• Task WriteAsync(params EventData[] events)

• void Write(IEnumerable<EventData> events)

• void Write(params EventData[] events)

• Task CommitAsync()

• void Commit()

• void Rollback()

##EventData

The writing methods all use a type named EventData to represent an event to be stored. Instances of EventData are immutable.

The Event Store does not have any built-in serialization, so the body and metadata for each event are represented in EventData as a byte[]. Some examples using popular serialization frameworks are available [here](wiki/Building-EventData-Instances-%28.NET API%29).

The members on EventData are:

• Guid EventId - A unique ID for the event. This is used in idempotency checks (see below).

• string Type - The name of the event type. This can be used later for pattern matching in projections, so should be a “friendly” name rather than a CLR type name, for example.

• bool IsJson - If the data and metadata fields are serialized as JSON, this should be set to true. Setting this to true will cause the projections framework to attempt to deserialize the data and metadata later.

• byte[] Data - The serialized data representing the event to be stored.

• byte[] Metadata - The serialized data representing metadata about the event to be stored.

##Appending to a stream in a single write

The AppendToStreamAsync and AppendToStream write events atomically to the end of a stream, working in an async and blocking manner respectively.

The parameters are:

• string stream - the name of the stream to which to append.

• int expectedVersion - the version at which we currently expect the stream to be in order that an optimistic concurrency check can be performed. This should either be a positive integer, or one of the constants ExpectedVersion.NoStream, ExpectedVersion.EmptyStream, or to disable the check, ExpectedVersion.Any. See here for a broader discussion of this.

• IEnumerable<EventData> events - the events to append. There is also an overload of each method which takes the events as a params array.