KurrentDB Client integration reference

⭐ Community Toolkit

To get started with the Aspire KurrentDB integrations, follow the Get started with KurrentDB integrations guide.

This article includes full details about the Aspire KurrentDB Client integration.

Installation

To install the 📦 CommunityToolkit.Aspire.KurrentDB NuGet package in the client-consuming project:

.NET CLI

.NET CLI — Add CommunityToolkit.Aspire.KurrentDB package

dotnet add package CommunityToolkit.Aspire.KurrentDB

Program.cs (C# file-based app)

Program.cs

#:package CommunityToolkit.Aspire.KurrentDB@*

PackageReference (*.csproj)

XML — Add CommunityToolkit.Aspire.KurrentDB package reference

<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 a KurrentDBClient for use via the dependency injection container.

C# — Program.cs

builder.AddKurrentDBClient(connectionName: "kurrentdb");

Tip

The connectionName parameter must match the name used when adding the KurrentDB resource in the AppHost project.

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

C# — ExampleService.cs

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:

C# — Program.cs

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

Then retrieve the instances using dependency injection:

C# — ExampleService.cs

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:

C# — Program.cs

builder.AddKurrentDBClient("kurrentdb");

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

JSON — appsettings.json

{
  "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:

JSON — 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:

C# — Program.cs

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.