Skip to content

Latest commit

 

History

History
249 lines (163 loc) · 10.5 KB

hosting-eventstore.md

File metadata and controls

249 lines (163 loc) · 10.5 KB
title description ms.date
.NET Aspire Community Toolkit EventStore integration
Learn how to use the .NET Aspire EventStore hosting and client integration to run the EventStore container and accessing it via the EventStore client.
11/21/2024

.NET Aspire Community Toolkit EventStore integration

[!INCLUDE includes-hosting-and-client]

[!INCLUDE banner]

In this article, you learn how to use the .NET Aspire EventStore hosting integration to run EventStore container and accessing it via the EventStore client.

Hosting integration

To run the EventStore container, install the 📦 CommunityToolkit.Aspire.Hosting.EventStore NuGet package in the app host project.

.NET CLI

dotnet add package CommunityToolkit.Aspire.Hosting.EventStore

PackageReference

<PackageReference Include="CommunityToolkit.Aspire.Hosting.EventStore"
                  Version="*" />

For more information, see dotnet add package or Manage package dependencies in .NET applications.

Add EventStore resource

In the app host project, register and consume the EventStore integration using the AddEventStore extension method to add the EventStore container to the application builder.

var builder = DistributedApplication.CreateBuilder(args);

var eventstore = builder.AddEventStore("eventstore");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(eventstore);

// After adding all resources, run the app...

When .NET Aspire adds a container image to the app host, as shown in the preceding example with the docker.io/eventstore/eventstore image, it creates a new EventStore instance on your local machine. A reference to your EventStore resource (the eventstore variable) is added to the ExampleProject.

For more information, see Container resource lifecycle.

Add EventStore resource with data volume

To add a data volume to the EventStore resource, call the Aspire.Hosting.EventStoreBuilderExtensions.WithDataVolume method on the EventStore resource:

var builder = DistributedApplication.CreateBuilder(args);

var eventstore = builder.AddEventStore("eventstore")
                        .WithDataVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(eventstore);

// After adding all resources, run the app...

The data volume is used to persist the EventStore data outside the lifecycle of its container. The data volume is mounted at the /var/lib/eventstore path in the EventStore container and when a name parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see Docker docs: Volumes.

Add EventStore resource with data bind mount

To add a data bind mount to the EventStore resource, call the Aspire.Hosting.EventStoreBuilderExtensions.WithDataBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

var eventstore = builder.AddEventStore("eventstore")
                        .WithDataBindMount(source: @"C:\EventStore\Data");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(eventstore);

// After adding all resources, run the app...

[!INCLUDE data-bind-mount-vs-volumes]

Data bind mounts rely on the host machine's filesystem to persist the EventStore data across container restarts. The data bind mount is mounted at the C:\EventStore\Data on Windows (or /EventStore/Data on Unix) path on the host machine in the EventStore container. For more information on data bind mounts, see Docker docs: Bind mounts.

Add EventStore resource with log volume

To add a log volume to the EventStore resource, call the Aspire.Hosting.EventStoreBuilderExtensions.WithLogVolume method on the EventStore resource:

var builder = DistributedApplication.CreateBuilder(args);

var eventstore = builder.AddEventStore("eventstore")
                        .WithLogVolume();

builder.AddProject<Projects.ExampleProject>()
       .WithReference(eventstore);

// After adding all resources, run the app...

The data volume is used to persist the EventStore logs outside the lifecycle of its container. The data volume is mounted at the /var/logs/eventstore path in the EventStore container and when a name parameter isn't provided, the name is generated at random. For more information on data volumes and details on why they're preferred over bind mounts, see Docker docs: Volumes.

Add EventStore resource with log bind mount

To add a log bind mount to the EventStore resource, call the Aspire.Hosting.EventStoreBuilderExtensions.WithLogBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

var eventstore = builder.AddEventStore("eventstore")
                        .WithLogBindMount(source: @"C:\EventStore\Logs");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(eventstore);

// After adding all resources, run the app...

[!INCLUDE data-bind-mount-vs-volumes]

Data bind mounts rely on the host machine's filesystem to persist the EventStore logs across container restarts. The data bind mount is mounted at the C:\EventStore\Logs on Windows (or /EventStore/Logs on Unix) path on the host machine in the EventStore container. For more information on data bind mounts, see Docker docs: Bind mounts.

Client integration

To get started with the .NET Aspire EventStore client integration, install the 📦 CommunityToolkit.Aspire.EventStore NuGet package in the client-consuming project, that is, the project for the application that uses the EventStore client.

.NET CLI

dotnet add package CommunityToolkit.Aspire.EventStore

PackageReference

<PackageReference Include="CommunityToolkit.Aspire.EventStore"
                  Version="*" />

Add EventStore client

In the :::no-loc text="Program.cs"::: file of your client-consuming project, call the Microsoft.Extensions.Hosting.AspireEventStoreExtensions.AddEventStoreClient extension method on any xref:Microsoft.Extensions.Hosting.IHostApplicationBuilder to register an EventStoreClient for use via the dependency injection container. The method takes a connection name parameter.

builder.AddEventStoreClient(connectionName: "eventstore");

Tip

The connectionName parameter must match the name used when adding the EventStore resource in the app host project. For more information, see Add EventStore resource.

You can then retrieve the EventStoreClient instance using dependency injection. For example, to retrieve the connection from an example service:

public class ExampleService(EventStoreClient client)
{
    // Use client...
}

Add keyed EventStore client

There might be situations where you want to register multiple EventStoreClient instances with different connection names. To register keyed EventStore clients, call the Microsoft.Extensions.Hosting.AspireEventStoreExtensions.AddKeyedEventStoreClient

builder.AddKeyedEventStoreClient(name: "accounts");
builder.AddKeyedEventStoreClient(name: "orders");

Then you can retrieve the EventStoreClient instances using dependency injection. For example, to retrieve the connection from an example service:

public class ExampleService(
    [FromKeyedServices("accounts")] EventStoreClient accountsClient,
    [FromKeyedServices("orders")] EventStoreClient ordersClient)
{
    // Use clients...
}

For more information on keyed services, see .NET dependency injection: Keyed services.

Configuration

The .NET Aspire EventStore client integration provides multiple options to configure the server connection based on the requirements and conventions of your project.

Use a connection string

When using a connection string from the ConnectionStrings configuration section, you can provide the name of the connection string when calling builder.AddEventStoreClient:

builder.AddEventStoreClient("eventstore");

Then the connection string will be retrieved from the ConnectionStrings configuration section:

{
  "ConnectionStrings": {
    "eventstore": "esdb://localhost:22113?tls=false"
  }
}

Use configuration providers

The .NET Aspire EventStore Client integration supports xref:Microsoft.Extensions.Configuration. It loads the CommunityToolkit.Aspire.EventStore.EventStoreSettings from configuration by using the Aspire:EventStore:Client key. Consider the following example appsettings.json that configures some of the options:

{
  "Aspire": {
    "EventStore": {
      "Client": {
        "ConnectionString": "esdb://localhost:22113?tls=false",
        "DisableHealthChecks": true
      }
    }
  }
}

Use inline delegates

Also you can pass the Action<EventStoreSettings> configureSettings delegate to set up some or all the options inline, for example to set the API key from code:

builder.AddEventStoreClient(
    "eventstore",
    static settings => settings.DisableHealthChecks = true);

Client integration health checks

The .NET Aspire EventStore integration uses the configured client to perform a IsHealthyAsync. If the result is true, the health check is considered healthy, otherwise it's unhealthy. Likewise, if there's an exception, the health check is considered unhealthy with the error propagating through the health check failure.

See also