Event Store logo

Menu

Documentation

Show Table of Contents

Embedded Client

EmbeddedVNodeBuilder

The EmbeddedVNodeBuilder class is responsible for setting up and building an Event Store node. You can configure your node through a number of methods provided by EmbeddedVNodeBuilder.

The builder that is used for the EmbeddedVNodeBuilder is the same as the one we use internally to create the ClusterNode, so check EventStore.ClusterNode.Program.cs for more examples of how to use it.

Building a node

You have two options when you start creating a node: EmbeddedVNodeBuilder.AsSingleNode() or EmbeddedVNodeBuilder.AsClusterMember(clusterSize), which will create a single node or a cluster node respectively. After creating the builder, you can configure the node through the methods provided by the EmbeddedVNodeBuilder. These will be listed further down.

Once you have configured the node, build it with EmbeddedVNodeBuilder.Build() which will return the configured ClusterVNode.

Start the node with ClusterVNode.StartAndWaitUntilReady() or ClusterVNode.Start(). ClusterVNode.StartAndWaitUntilReady() returns a task that will complete once the node has started up and all subsystems have finished loading.

For example, to build a single node with default options :

var nodeBuilder = EmbeddedVNodeBuilder.AsSingleNode()
                                      .OnDefaultEndpoints()
                                      .RunInMemory();
var node = nodeBuilder.Build();
node.StartAndWaitUntilReady().Wait();

To build a node to be part of a cluster with custom endpoints and gossip seeds :

var nodeBuilder = EmbeddedVNodeBuilder.AsClusterMember(3)
                      .RunOnDisk("node1db")
                      .WithInternalHttpOn(new IPEndPoint(IPAddress.Loopback, 1112))
                      .WithExternalHttpOn(new IPEndPoint(IPAddress.Loopback, 1113))
                      .WithExternalTcpOn(new IPEndPoint(IPAddress.Loopback, 1114))
                      .WithInternalTcpOn(new IPEndPoint(IPAddress.Loopback, 1115))
                      .DisableDnsDiscovery()
                      .WithGossipSeeds(new IPEndPoint[]
                      {
                          new IPEndPoint(IPAddress.Loopback, 2112),
                          new IPEndPoint(IPAddress.Loopback, 3112)
                      });
var node = nodeBuilder.Build();
node.Start();

When running an embedded cluster, the task returned by StartAndWaitUntilReady() will only complete on the master node.

Connecting to an embedded node

You can connect to an embedded Event Store node with the EmbeddedEventStoreConnection class. Calling EmbeddedEventStoreConnection.Create(ClusterVNode) will return an IEventStoreConnection configured to connect to your embedded node. From there you can use the connection as you normally would in the .NET Client.

using(var embeddedConn = EmbeddedEventStoreConnection.Create(node))
{
    embeddedConn.ConnectAsync().Wait();
    embeddedConn.AppendToStreamAsync("testStream", ExpectedVersion.Any, 
                    new EventData(Guid.NewGuid(), "eventType", true, 
                    Encoding.UTF8.GetBytes("{\"Foo\":\"Bar\"}"), null)).Wait();
}

Logging with an embedded node

In order to enable logging for an embedded node, you need to initialise the LogManager and ensure that you configure the logger with a log.config file in your configuration directory.

To initialise the LogManager, call this before building the nodes :

LogManager.Init(logComponentName, logDirectory, logConfigurationDirectory);

EmbeddedVNodeBuilder options

The following options are available when building an Embedded Node

Application Options

Method Description
AsSingleNode() Returns a builder set to construct options for a single node instance
AsClusterMember(int clusterSize) Returns a builder set to construct options for a cluster node instance with a cluster size
DisableHTTPCaching() Disable HTTP Caching
WithWorkerThreads(int count) Sets the number of worker threads to use in shared threadpool
WithStatsPeriod(TimeSpan statsPeriod) Sets the period between statistics gathers
EnableLoggingOfHttpRequests() Enable logging of Http Requests and Responses before they are processed
EnableHistograms() Enable the tracking of various histograms in the backend, typically only used for debugging
EnableTrustedAuth() Enable trusted authentication by an intermediary in the HTTP

Certificate options

Method Description
WithServerCertificateFromFile(string path, string password) Sets the Server SSL Certificate to be loaded from a file
WithServerCertificate(X509Certificate2 sslCertificate) Sets the Server SSL Certificate
WithServerCertificateFromStore(StoreLocation storeLocation, StoreName storeName, string certificateSubjectName, string certificateThumbprint) Sets the Server SSL Certificate to be loaded from a certificate store
WithServerCertificateFromStore(StoreName storeName, string certificateSubjectName, string certificateThumbprint) Sets the Server SSL Certificate to be loaded from a certificate store

Cluster options

Method Description
WithClusterGossipPort(int port) Sets the internal gossip port (used when using cluster dns, this should point to a known port gossip will be running on)
WithGossipSeeds(params IPEndPoint[] endpoints) Sets the gossip seeds this node should talk to
WithClusterDnsName(string name) Sets the dns name used for the discovery of other cluster nodes
DisableDnsDiscovery() Disable dns discovery for the cluster
WithGossipInterval(TimeSpan gossipInterval) Sets the gossip interval
WithGossipAllowedTimeDifference(TimeSpan gossipAllowedDifference) Sets the allowed gossip time difference
WithGossipTimeout(TimeSpan gossipTimeout) Sets the gossip timeout
WithPrepareTimeout(TimeSpan prepareTimeout) Sets the prepare timeout
WithCommitTimeout(TimeSpan commitTimeout) Sets the commit timeout
WithPrepareCount(int prepareCount) Sets the number of nodes which must acknowledge prepares.
WithCommitCount(int commitCount) Sets the number of nodes which must acknowledge commits before acknowledging to a client.
WithNodePriority(int nodePriority) Sets the node priority used during master election

Database options

Method Description
RunInMemory() Sets the builder to run in memory only
RunOnDisk(string path) Sets the builder to write database files to the specified path
MaximumMemoryTableSizeOf(int size) Sets the maximum size a memtable is allowed to reach (in count) before being moved to be a ptable
DoNotVerifyDbHashes() Marks that the existing database files should not be checked for checksums on startup.
VerifyDbHashes() Marks that the existing database files should be checked for checksums on startup.
WithMinFlushDelay(TimeSpan minFlushDelay) Sets the minimum flush delay
DisableScavengeMerging() Disables the merging of chunks when scavenge is running
WithScavengeHistoryMaxAge(int scavengeHistoryMaxAge) The number of days to keep scavenge history (Default: 30)
WithIndexPath(string indexPath) Sets the path the index should be loaded/saved to
WithIndexCacheDepth(int indexCacheDepth) Sets the depth to cache for the mid point cache in index
WithUnsafeIgnoreHardDelete() Disables Hard Deletes (UNSAFE: use to remove hard deletes)
WithUnsafeDisableFlushToDisk() Disables Hard Deletes (UNSAFE: use to remove hard deletes)
WithBetterOrdering() Enable Queue affinity on reads during write process to try to get better ordering.
WithTfChunkSize(int chunkSize) Sets the transaction file chunk size. Default is
WithTfChunksCacheSize(long chunksCacheSize) Sets the transaction file chunk cache size. Default is
WithTfCachedChunks(int cachedChunks) The number of chunks to cache in unmanaged memory.

Interface options

Method Description
OnDefaultEndpoints() Sets the default endpoints on localhost (1113 tcp, 2113 http)
AdvertiseInternalIPAs(IPAddress intIpAdvertiseAs) Sets up the Internal IP that would be advertised
AdvertiseExternalIPAs(IPAddress extIpAdvertiseAs) Sets up the External IP that would be advertised
AdvertiseInternalHttpPortAs(int intHttpPortAdvertiseAs) Sets up the Internal Http Port that would be advertised
AdvertiseExternalHttpPortAs(int extHttpPortAdvertiseAs) Sets up the External Http Port that would be advertised
AdvertiseInternalSecureTCPPortAs(int intSecureTcpPortAdvertiseAs) Sets up the Internal Secure TCP Port that would be advertised
AdvertiseExternalSecureTCPPortAs(int extSecureTcpPortAdvertiseAs) Sets up the External Secure TCP Port that would be advertised
AdvertiseInternalTCPPortAs(int intTcpPortAdvertiseAs) Sets up the Internal TCP Port that would be advertised
AdvertiseExternalTCPPortAs(int extTcpPortAdvertiseAs) Sets up the External TCP Port that would be advertised
WithInternalHttpOn(IPEndPoint endpoint) Sets the internal http endpoint to the specified value
WithExternalHttpOn(IPEndPoint endpoint) Sets the external http endpoint to the specified value
WithInternalTcpOn(IPEndPoint endpoint) Sets the internal tcp endpoint to the specified value
WithInternalSecureTcpOn(IPEndPoint endpoint) Sets the internal secure tcp endpoint to the specified value
WithExternalTcpOn(IPEndPoint endpoint) Sets the external tcp endpoint to the specified value
WithExternalSecureTcpOn(IPEndPoint endpoint) Sets the external secure tcp endpoint to the specified value
EnableSsl() Sets that SSL should be used on connections
WithSslTargetHost(string targetHost) Sets the target host of the server's SSL certificate.
ValidateSslServer() Sets whether to validate that the server's certificate is trusted.
NoGossipOnPublicInterface() Disables gossip on the public (client) interface
NoAdminOnPublicInterface() Disables the admin interface on the public (client) interface
NoStatsOnPublicInterface() Disables statistics screens on the public (client) interface
AddInternalHttpPrefix(string prefix) Adds a http prefix for the internal http endpoint
AddExternalHttpPrefix(string prefix) Adds a http prefix for the external http endpoint
DontAddInterfacePrefixes() Don't add the interface prefixes (e.g. If the External IP is set to the Loopback address, we'll add http://localhost:2113/ as a prefix)
WithInternalHeartbeatInterval(TimeSpan heartbeatInterval) Sets the heartbeat interval for the internal network interface.
WithExternalHeartbeatInterval(TimeSpan heartbeatInterval) Sets the heartbeat interval for the external network interface.
WithInternalHeartbeatTimeout(TimeSpan heartbeatTimeout) Sets the heartbeat timeout for the internal network interface.
WithExternalHeartbeatTimeout(TimeSpan heartbeatTimeout) Sets the heartbeat timeout for the external network interface.

Projections options

Method Description
StartStandardProjections() Start standard projections.
RunProjections(ProjectionType projectionType, int numberOfThreads = Opts.ProjectionThreadsDefault) Sets the mode and the number of threads on which to run projections.
RunProjections(ClientAPI.Embedded.ProjectionsMode projectionsMode, int numberOfThreads = Opts.ProjectionThreadsDefault) Sets the mode and the number of threads on which to run projections.

EmbeddedEventStoreConnection

The following methods are available on EmbeddedEventStoreConnection for connecting to an embedded node

Method Description
Create(ClusterVNode eventStore, string connectionName = null) Creates a new embedded IEventStoreConnection to a single node with default connection settings
Create(ClusterVNode eventStore, ConnectionSettings connectionSettings, string connectionName = null) Creates a new embedded IEventStoreConnection to a single node using specific ConnectionSettings

Event Store docs are hosted on GitHub. The repository is public and it’s open to issues and pull requests. Contributions, corrections and feedback are all welcome.