KurrentDB integration

このコンテンツはまだ日本語訳がありません。

⭐ Community Toolkit

KurrentDB is an event store database designed for Event Sourcing, offering high availability and reliability for storing events. The Aspire KurrentDB integration enables you to connect to existing KurrentDB instances or create new instances from Aspire using the KurrentDB container image.

Hosting integration

To run the KurrentDB container, install the 📦 CommunityToolkit.Aspire.Hosting.KurrentDB NuGet package in the AppHost project.

aspire add communitytoolkit-kurrentdb

Aspire CLI は対話的です。求められたら適切な結果を選択してください:

Select an integration to add:

> communitytoolkit-kurrentdb (CommunityToolkit.Aspire.Hosting.KurrentDB)
> Other results listed as selectable options...

#:package CommunityToolkit.Aspire.Hosting.KurrentDB@*

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

Add KurrentDB resource

In the AppHost project, register and consume the KurrentDB integration using the AddKurrentDB extension method to add the KurrentDB container to the application builder.

var builder = DistributedApplication.CreateBuilder(args);

var kurrentdb = builder.AddKurrentDB("kurrentdb");

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

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

Add KurrentDB resource with data volume

To add a data volume to the KurrentDB resource, call the WithDataVolume method:

var builder = DistributedApplication.CreateBuilder(args);

var kurrentdb = builder.AddKurrentDB("kurrentdb")
                       .WithDataVolume();

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

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

The data volume is used to persist the KurrentDB data outside the lifecycle of its container. The data volume is mounted at the /var/lib/kurrentdb path in the KurrentDB container.

Add KurrentDB resource with data bind mount

To add a data bind mount to the KurrentDB resource, call the WithDataBindMount method:

var builder = DistributedApplication.CreateBuilder(args);

var kurrentdb = builder.AddKurrentDB("kurrentdb")
                       .WithDataBindMount(source: @"C:\KurrentDB\Data");

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

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

Hosting integration health checks

The KurrentDB hosting integration automatically adds a health check for the KurrentDB resource. The health check verifies that the KurrentDB instance is running and that a connection can be established to it.

Client integration

To get started with the Aspire KurrentDB client integration, install the 📦 CommunityToolkit.Aspire.KurrentDB NuGet package in the client-consuming project:

dotnet add package CommunityToolkit.Aspire.KurrentDB

#:package CommunityToolkit.Aspire.KurrentDB@*

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

Add KurrentDB client

In the Program.cs file of your client-consuming project, call the AddKurrentDBClient extension to register an KurrentDBClient for use via the dependency injection container.

builder.AddKurrentDBClient(connectionName: "kurrentdb");

You can then retrieve the KurrentDBClient instance using dependency injection. For example, to retrieve the client from a service:

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

Add keyed KurrentDB client

There might be situations where you want to register multiple KurrentDBClient instances with different connection names. To register keyed KurrentDB clients, call the AddKeyedKurrentDBClient method:

builder.AddKeyedKurrentDBClient(name: "events");
builder.AddKeyedKurrentDBClient(name: "audit");

Then retrieve the instances using dependency injection:

public class ExampleService(
    [FromKeyedServices("events")] KurrentDBClient eventsClient,
    [FromKeyedServices("audit")] KurrentDBClient auditClient)
{
    // Use clients...
}

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

Configuration

The KurrentDB client integration provides multiple configuration approaches and options to meet 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 AddKurrentDBClient:

builder.AddKurrentDBClient("kurrentdb");

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

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

Use configuration providers

The KurrentDB client integration supports Microsoft.Extensions.Configuration. It loads the KurrentDBSettings from configuration using the Aspire:KurrentDB:Client key. Example appsettings.json:

{
  "Aspire": {
    "KurrentDB": {
      "Client": {
        "ConnectionString": "kurrentdb://localhost:22113?tls=false",
        "DisableHealthChecks": false,
        "DisableTracing": false
      }
    }
  }
}

Use inline delegates

You can pass the delegate to set up options inline:

builder.AddKurrentDBClient(
    "kurrentdb",
    static settings => settings.DisableHealthChecks = true);

Client integration health checks

By default, Aspire integrations enable health checks for all services. The KurrentDB integration adds a health check that verifies the KurrentDB instance is reachable and can execute commands.

Observability and telemetry

Logging

The KurrentDB integration uses the following log categories:

Aspire.KurrentDB

Tracing

The KurrentDB integration emits tracing activities using OpenTelemetry when tracing is not disabled.