Foundationdb Aspire

FoundationDB — Running a cluster & connecting from .NET (Aspire, the native client)

The foundationdb-keys-and-layers, foundationdb-transactions, and foundationdb-advanced-layers skills all start from an IFdbDatabase / IFdbDatabaseProvider you already have. This skill is about getting there: standing up a cluster, loading the native client correctly, and connecting — including the .NET Aspire integration shipped in this repo (FoundationDB.Aspire.Hosting + FoundationDB.Aspire).

1. Getting an IFdbDatabaseProvider

Application code resolves an IFdbDatabaseProvider (then await provider.GetDatabase(ct) or, more commonly, the retry-loop methods). Three ways to create one:

apiVersion selects the client API level and caps the features you can use: 730 ⇒ FoundationDB 7.3 semantics, 740 ⇒ 7.4. This client accepts 610 to 740, and Fdb.DefaultApiVersion is 730, which is why 730 appears in most examples. Pick the level whose semantics you actually rely on, not the newest available: raising it is a behavior change, and it must stay ≤ what the cluster supports. The provider also carries a root FdbPath (a directory-layer partition); everything else resolves relative to it.

Plain-DI / no-DI namespaces: FoundationDB.DependencyInjection. These all still need the native client loaded (§5).

2. The Aspire AppHost integration (FoundationDB.Aspire.Hosting)

On a IDistributedApplicationBuilder (the AppHost), namespace Aspire.Hosting:

// starts a FoundationDB cluster as a Docker container, and emits a connection string named "fdb"
var fdb = builder.AddFoundationDb("fdb",
        apiVersion: 730,
        root: "/MyApp")                            // clusterVersion omitted on purpose - see below
    .WithLifetime(ContainerLifetime.Persistent);   // reuse the container across runs (faster restarts)

builder.AddProject<Projects.MyApp>("app")
    .WithReference(fdb)                            // injects the "fdb" connection string into the app
    .WaitFor(fdb);                                 // hold the app until the cluster is healthy

• Prefer omitting clusterVersion. Left out, the hosting package picks its own last-known-good Docker tag for the major it selects (the FdbAspireHostingExtensions.LatestVersionNN constants, refreshed from Docker Hub by scripts/check-fdb-image-tags.ps1). A tag you hardcode is a number that rots in your AppHost: pin one only when you need a specific image, and then treat it as something to review, alongside rollForward: FdbVersionPolicy.Exact.
• AddFoundationDb(...) → IResourceBuilder<FdbClusterResource> runs a container.
• A fresh volume self-provisions. On first start the integration runs configure new single ssd inside the container (a brand-new cluster has no database until then), and WaitFor(fdb) holds dependents until the database answers. An already-configured database is left untouched. Opt out with .WithAutoProvisioning(false); run mode only.
• AddFoundationDbCluster(name, apiVersion, root, clusterFile?, clusterVersion?) → IResourceBuilder<FdbConnectionResource> instead connects to an already-running cluster (no container) given a cluster file.
• Give each AppHost its own data volume with .WithDataVolume() (name generated from the AppHost and the resource) or .WithDataVolume("name"). The default volume fdb_data is shared by every AppHost on the machine that keeps it: two clusters on it fail with "Unable to lock the file", and a 7.4 server upgrades 7.3 data files in place, beyond the reach of 7.3 servers.
• FdbVersionPolicy (Exact, etc.) lives in Aspire.Hosting.ApplicationModel. .WithDefaults(timeout, retryLimit, tracing) tunes the connection.
• Interactive tools in the dashboard (run mode only): .WithFdbCli() adds an "FdbCli" command that opens fdbcli inside the container, in the terminal dock. .WithFdbShell() adds an "FdbShell" command that runs the FdbShell .NET tool from NuGet (dotnet tool exec, no package reference) with the cluster's connection string, starting in the root folder; it runs the FdbShell of the same version as the hosting package (released together, so they agree on the --aspire contract), and FdbShell loads the libfdb_c of the cluster's branch from the AppHost's output: the AppHost must reference FoundationDB.Client.Native of the cluster's major.minor (same CPM version as the apps), or WithFdbShell() throws at startup with the fix (also on a branch mismatch). In a solution that holds the FdbShell source, .WithFdbShell<Projects.FdbShell>() runs the project instead (needs a ProjectReference to FdbShell.csproj pinned to the AppHost's TFM with SetTargetFramework). Do not add FdbShell as a project resource: it needs a terminal. Outside the AppHost, fdbshell --aspire / fdbtop --aspire read the same ConnectionStrings__<name> variable, and fail with an actionable error when it is missing.

AppHost project setup: Sdk="Aspire.AppHost.Sdk/<ver>"; reference FoundationDB.Aspire.Hosting with IsAspireProjectResource="false" (it's a compile dependency for AddFoundationDb); reference each app project normally (those are launched as resources — their TFM need not match the AppHost).

3. The Aspire client integration (FoundationDB.Aspire)

In the app (not the AppHost), on an IHostApplicationBuilder, namespace Microsoft.Extensions.Hosting:

// reads the "fdb" connection string injected by WithReference(fdb) and registers IFdbDatabaseProvider
builder.AddFoundationDb("fdb",
    settings => { /* FdbClientSettings: tracing, health checks, … */ },
    options  => options.UseNativeClient());        // load libfdb_c (see §5)

The app references FoundationDB.Aspire. The injected connection string looks like ApiVersion=730;Root=/MyApp;ClusterFileContents=…;ClusterVersion=7.4.6 (the ClusterVersion is whatever tag the AppHost resolved, so do not read the one in this example as a recommendation). Standalone (no AppHost), provide the cluster file via configuration instead.

Don't confuse the two AddFoundationDbs: the AppHost one (IDistributedApplicationBuilder, starts the container) vs the client one (IHostApplicationBuilder, consumes the connection). They have different receivers, so they never collide.

4. Launching the AppHost

Preferred: the aspire CLI — it provisions the dashboard, OTLP, and ports for you:

dotnet tool install --global aspire.cli          # one-time
aspire run --apphost path/to/MyApp.AppHost.csproj
# headless / CI: aspire run --apphost … --detach --non-interactive --format Json
#   → returns { appHostPid, dashboardUrl (with login token), logFile }

Fallback: plain dotnet run (or IDE F5) on the AppHost. This requires a Properties/launchSettings.json providing the dashboard + OTLP endpoints, e.g.:

{ "profiles": { "http": { "commandName": "Project",
  "applicationUrl": "http://localhost:15200",
  "environmentVariables": {
    "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:19200",
    "DOTNET_RESOURCE_SERVICE_ENDPOINT_URL": "http://localhost:20200",
    "ASPIRE_ALLOW_UNSECURED_TRANSPORT": "true" } } } }

Without it, a bare dotnet run on the AppHost crashes at startup: "Failed to configure dashboard resource because ASPNETCORE_URLS … was not set / … OTLP endpoint must be provided." The aspire CLI does not need this file.