Set up KurrentDB in the AppHost

⭐ Community Toolkit

This article is the reference for the Aspire KurrentDB Hosting integration. It enumerates the AppHost APIs that you use to model a KurrentDB resource in your AppHost project.

If you’re new to the KurrentDB integration, start with the Get started with KurrentDB integrations guide. For how consuming apps read the connection information this page exposes, see Connect to KurrentDB.

Installation

To start building an Aspire app that uses KurrentDB, install the 📦 CommunityToolkit.Aspire.Hosting.KurrentDB NuGet package:

TypeScript

Terminal

aspire add CommunityToolkit.Aspire.Hosting.KurrentDB

Learn more about aspire add in the command reference.

This updates your aspire.config.json with the KurrentDB hosting integration package:

aspire.config.json

{
  "packages": {
    "CommunityToolkit.Aspire.Hosting.KurrentDB": "*"
  }
}

C#

Aspire CLI

Aspire CLI — CommunityToolkit.Aspire.Hosting.KurrentDB パッケージを追加

aspire add communitytoolkit-kurrentdb

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

Aspire CLI — 出力例

Select an integration to add:

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

ノート

結果が 1 つだけなら自動的に選択されます。バージョンは確認が必要です。

apphost.cs (C# file-based app)

C# — AppHost.cs

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

PackageReference (*.csproj)

XML — CommunityToolkit.Aspire.Hosting.KurrentDB パッケージ参照を追加

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

Or, choose a manual installation approach:

AppHost.cs

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

AppHost.csproj

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

Add KurrentDB resource

Once you’ve installed the hosting integration in your AppHost project, you can add a KurrentDB resource as shown in the following example:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const kurrentdb = await builder.addKurrentDB("kurrentdb");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(kurrentdb);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(kurrentdb);

builder.Build().Run();

1. When Aspire adds a container image to the AppHost, as shown in the preceding example with the docker.kurrent.io/kurrent-latest/kurrentdb image, it creates a new KurrentDB instance on your local machine.

2. The AppHost reference call configures a connection in the consuming project named after the referenced KurrentDB resource, such as kurrentdb in the preceding example.

ノート

When you reference a KurrentDB resource from the AppHost, Aspire makes several properties available to the consuming project, such as connection URIs, hostnames, and port numbers. For a complete list of these properties and per-language connection examples, see Connect to KurrentDB.

Add KurrentDB resource with data volume

Add a data volume to the KurrentDB resource as shown in the following example:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const kurrentdb = await builder.addKurrentDB("kurrentdb");
await kurrentdb.withDataVolume();

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(kurrentdb);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(kurrentdb);

builder.Build().Run();

The data volume is used to persist KurrentDB data outside the lifecycle of its container. The data volume is mounted at the /var/lib/kurrentdb path in the KurrentDB 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 KurrentDB resource with data bind mount

Add a data bind mount to the KurrentDB resource as shown in the following example:

TypeScript

apphost.mts

import { createBuilder } from './.aspire/modules/aspire.mjs';

const builder = await createBuilder();

const kurrentdb = await builder.addKurrentDB("kurrentdb");
await kurrentdb.withDataBindMount("C:\\KurrentDB\\Data");

const exampleProject = await builder.addProject("apiservice", "../ExampleProject/ExampleProject.csproj");
await exampleProject.withReference(kurrentdb);

await builder.build().run();

C#

AppHost.cs

var builder = DistributedApplication.CreateBuilder(args);

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

var exampleProject = builder.AddProject<Projects.ExampleProject>("apiservice")
    .WithReference(kurrentdb);

builder.Build().Run();

ノート

Data bind mounts have limited functionality compared to volumes, which offer better performance, portability, and security, making them more suitable for production environments. However, bind mounts allow direct access and modification of files on the host system, ideal for development and testing where real-time changes are needed.

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

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. The health check is wired into the /health HTTP endpoint, where all registered health checks must pass before the app is considered ready to accept traffic.