foundationdb-aspire
How to run a FoundationDB cluster and connect to it from .NET — getting the IFdbDatabaseProvider that the keys/transactions/layers skills assume you already have. Covers the ways to get a provider (plain DI services.AddFoundationDb, FdbDatabaseProvider.Create, or Aspire), the Asp
Install
npx skills add https://github.com/SnowBankSDK/foundationdb-dotnet-client/tree/master/.claude/skills/foundationdb-aspire
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install snowbanksdk-foundationdb-dotnet-client@llmmart
git clone https://github.com/SnowBankSDK/foundationdb-dotnet-client.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole snowbanksdk/foundationdb-dotnet-client collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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:
| Way | API | When |
|---|---|---|
| Plain DI | services.AddFoundationDb(apiVersion, opt => …) → IFdbDatabaseProviderBuilder (registers IFdbDatabaseProvider) |
a regular host, you supply the cluster file via config |
| No DI | FdbDatabaseProvider.Create(new FdbDatabaseProviderOptions { ApiVersion = 730, … }) |
tools/tests/standalone; call provider.Start() |
| Aspire client | builder.AddFoundationDb("fdb", settings, options) |
the connection string is injected by an Aspire AppHost (see §3) |
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 (theFdbAspireHostingExtensions.LatestVersionNNconstants, refreshed from Docker Hub byscripts/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, alongsiderollForward: FdbVersionPolicy.Exact. AddFoundationDb(...)→IResourceBuilder<FdbClusterResource>runs a container.- A fresh volume self-provisions. On first start the integration runs
configure new single ssdinside the container (a brand-new cluster has no database until then), andWaitFor(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 volumefdb_datais 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 inAspire.Hosting.ApplicationModel..WithDefaults(timeout, retryLimit, tracing)tunes the connection.- Interactive tools in the dashboard (run mode only):
.WithFdbCli()adds an "FdbCli" command that opensfdbcliinside the container, in the terminal dock..WithFdbShell()adds an "FdbShell" command that runs theFdbShell.NET tool from NuGet (dotnet tool exec, no package reference) with the cluster's connection string, starting in therootfolder; it runs the FdbShell of the same version as the hosting package (released together, so they agree on the--aspirecontract), and FdbShell loads thelibfdb_cof the cluster's branch from the AppHost's output: the AppHost must referenceFoundationDB.Client.Nativeof the cluster's major.minor (same CPM version as the apps), orWithFdbShell()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 aProjectReferencetoFdbShell.csprojpinned to the AppHost's TFM withSetTargetFramework). Do not add FdbShell as a project resource: it needs a terminal. Outside the AppHost,fdbshell --aspire/fdbtop --aspireread the sameConnectionStrings__<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.
5. The native client (libfdb_c): where it loads from
The .NET client talks to the cluster through the native libfdb_c library. Since 7.4.7 the binding loads it from fixed paths only. With the default (FdbDatabaseProviderOptions.NativeLibraryPath left null), it checks, in this order:
runtimes/{rid}/native/under the application folder, then the application folder itself: where theFoundationDB.Client.Nativepackage deploys the library;- the location of the official client installer:
%ProgramFiles%oundationdbindb_c.dll(Windows),/usr/lib/libfdb_c.so(Linux),/usr/local/lib/libfdb_c.dylib(macOS).
It never searches PATH or LD_LIBRARY_PATH by default: those folders may be writable by other users or programs, and a library planted there would run inside the process. When none of the fixed paths holds the library, opening the database throws DllNotFoundException, and the message lists the paths it checked.
The three ways to provide the library:
- Recommended: reference
FoundationDB.Client.Nativewith the major.minor of the cluster (7.4.*for a 7.4 cluster,7.3.*for 7.3; see §6). It shipslibfdb_cforlinux-arm64,linux-x64,win-x64,osx-arm64andosx-x64, so the default above finds it with no extra call.options.UseNativeClient()(an extension of that package) pins the load to the package copy only, and reports a missing library withFileNotFoundExceptionwhile the services are configured, instead of when the database starts. - A library in another folder: set its full path.
- The operating-system search:
options.UseSystemNativeClient(), orUseNativeClient(allowSystemFallback: true)when the package copy is missing, restores the search of the runtime and the operating system, with the risk above. Use it only on a host you control.
services.AddFoundationDb(740, options => options.UseNativeClient()); // package copy only
services.AddFoundationDb(740, options => options.NativeLibraryPath = "/opt/foundationdb/lib/libfdb_c.so"); // explicit path
services.AddFoundationDb(740, options => options.UseSystemNativeClient()); // OS search, with its risk
Without dependency injection, Fdb.Options.SetNativeLibPath(path) sets the path.
Network options (for example the directory of the other client versions of the multi-version client) are set where the provider is registered, and the Aspire configureProvider callback can call it too:
services.AddFoundationDb(740, options => options
.SetNetworkOption(FdbNetworkOption.ExternalClientDirectory, "/opt/foundationdb/clients")
);
They apply in the order of the calls, after the trace and TLS options. The network thread starts once per process, so the options of the first provider that starts apply to the whole process.
6. Client ⇄ cluster version compatibility (the silent hang)
The client library version must be compatible with the cluster version. A 7.3 client cannot talk to a 7.4 cluster.
- Symptom: transactions hang (no exception);
fdbcliagainst the cluster reports "One or more processes … incompatible" and "database is unavailable", even though the cluster is internally healthy. - Fix: make the AppHost
clusterVersion(the Docker image tag) match thelibfdb_cavailable to the app. Check the client withfdbcli --version, the server withdocker exec <container> fdbcli --version. If you did not pin a tag, the mismatch is almost always a systemlibfdb_cshadowing the redistributed one (see §5), not the container. - The
apiVersion(e.g.730) must be ≤ the cluster's supported level;730⇒ 7.3,740⇒ 7.4.
For talking to multiple cluster versions from one process, FoundationDB's multi-version client loads several external libfdb_c libraries — but the simplest demo/dev setup is: one cluster version, one matching client library.
7. Golden rules & gotchas
✅ DO
- Pick the provider source by context: Aspire client integration under an AppHost; plain
services.AddFoundationDb(...)/FdbDatabaseProvider.Create(...)otherwise. - Launch the AppHost with
aspire run; keep alaunchSettings.jsononly as thedotnet run/F5 fallback. - Keep the cluster image and the client library on the same major.minor (7.4 with 7.4). Omitting
clusterVersionlets the hosting package pair them for you against thelibfdb_cthatFoundationDB.Client.Nativeredistributes; pin it only when you supply your own client library, and then verify both withfdbcli --version. - On macOS, the redistributed client covers
osx-arm64andosx-x64(since 7.4.6), soUseNativeClient(allowSystemFallback: false)works; fall back to a systemlibfdb_c.dylibandallowSystemFallback: trueonly for an older pin without your RID.
⚠️ GOTCHAS
- Transactions that hang on a brand-new cluster are almost always a client/cluster version mismatch, not a deadlock — check versions first.
DllNotFoundException: fdb_c⇒ none of the fixed paths holds the native client; the message lists them. AddFoundationDB.Client.Nativewith the major.minor of the cluster, or setNativeLibraryPath(see §5). A library only found throughPATHorLD_LIBRARY_PATHis no longer loaded by default.- AppHost
dotnet runcrash about ASPNETCORE_URLS / OTLP ⇒ missinglaunchSettings.json, or just useaspire run. AddFoundationDb"ambiguous" / wrong overload ⇒ you imported the wrong namespace; the AppHost call is onIDistributedApplicationBuilder(Aspire.Hosting), the client call onIHostApplicationBuilder(Microsoft.Extensions.Hosting).WithLifetime(ContainerLifetime.Persistent)keeps the cluster's data across runs — handy in dev, but remember todocker rm -fit when you want a clean slate.
8. File map
| What | Where |
|---|---|
| Aspire AppHost integration | FoundationDB.Aspire.Hosting/FdbAspireHostingExtensions.cs (AddFoundationDb, AddFoundationDbCluster, FdbVersionPolicy) |
| Aspire client integration | FoundationDB.Aspire/FdbAspireComponentExtensions.cs (AddFoundationDb), FdbClientSettings.cs |
| Plain DI / no-DI provider | FoundationDB.Client/DependencyInjection/FdbDatabaseServiceCollectionExtensions.cs, Implementation/FdbDatabaseProvider.cs |
| Native client loader | FoundationDB.Client.Native/ (FdbClientNativeExtensions.cs → UseNativeClient; runtimes/ holds the shipped libs) |
Files (foundationdb-dotnet-client)
-
SKILL.md 15.3 KB
--- name: foundationdb-aspire description: How to run a FoundationDB cluster and connect to it from .NET — getting the IFdbDatabaseProvider that the keys/transactions/layers skills assume you already have. Covers the ways to get a provider (plain DI services.AddFoundationDb, FdbDatabaseProvider.Create, or Aspire), the Aspire AppHost integration (FoundationDB.Aspire.Hosting — builder.AddFoundationDb starts a Docker cluster, AddFoundationDbCluster connects to an existing one), the Aspire client integration (FoundationDB.Aspire — builder.AddFoundationDb reads the injected connection), wiring with WithReference and WaitFor, launching with the aspire CLI vs plain dotnet run plus launchSettings, the native client (libfdb_c via UseNativeClient, the platforms FoundationDB.Client.Native ships, and the macOS system-library fallback), and the client-vs-cluster version-compatibility rule. Use whenever code opens or connects to a cluster, registers AddFoundationDb, runs an Aspire host, or hits libfdb_c load failures or transactions that hang on a fresh cluster. --- # 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: | Way | API | When | |---|---|---| | **Plain DI** | `services.AddFoundationDb(apiVersion, opt => …)` → `IFdbDatabaseProviderBuilder` (registers `IFdbDatabaseProvider`) | a regular host, you supply the cluster file via config | | **No DI** | `FdbDatabaseProvider.Create(new FdbDatabaseProviderOptions { ApiVersion = 730, … })` | tools/tests/standalone; call `provider.Start()` | | **Aspire client** | `builder.AddFoundationDb("fdb", settings, options)` | the connection string is injected by an Aspire AppHost (see §3) | `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`: ```csharp // 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`: ```csharp // 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 `AddFoundationDb`s: 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: ```bash 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.: ```json { "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. --- ## 5. The native client (`libfdb_c`): where it loads from The .NET client talks to the cluster through the native **`libfdb_c`** library. Since 7.4.7 the binding loads it from **fixed paths only**. With the default (`FdbDatabaseProviderOptions.NativeLibraryPath` left `null`), it checks, in this order: 1. `runtimes/{rid}/native/` under the application folder, then the application folder itself: where the `FoundationDB.Client.Native` package deploys the library; 2. the location of the official client installer: `%ProgramFiles%oundationdbindb_c.dll` (Windows), `/usr/lib/libfdb_c.so` (Linux), `/usr/local/lib/libfdb_c.dylib` (macOS). It never searches `PATH` or `LD_LIBRARY_PATH` by default: those folders may be writable by other users or programs, and a library planted there would run inside the process. When none of the fixed paths holds the library, opening the database throws `DllNotFoundException`, and the message lists the paths it checked. The three ways to provide the library: - **Recommended: reference `FoundationDB.Client.Native`** with the major.minor of the cluster (`7.4.*` for a 7.4 cluster, `7.3.*` for 7.3; see §6). It ships `libfdb_c` for `linux-arm64`, `linux-x64`, `win-x64`, `osx-arm64` and `osx-x64`, so the default above finds it with no extra call. `options.UseNativeClient()` (an extension of that package) pins the load to the package copy only, and reports a missing library with `FileNotFoundException` while the services are configured, instead of when the database starts. - **A library in another folder:** set its full path. - **The operating-system search:** `options.UseSystemNativeClient()`, or `UseNativeClient(allowSystemFallback: true)` when the package copy is missing, restores the search of the runtime and the operating system, with the risk above. Use it only on a host you control. ```csharp services.AddFoundationDb(740, options => options.UseNativeClient()); // package copy only services.AddFoundationDb(740, options => options.NativeLibraryPath = "/opt/foundationdb/lib/libfdb_c.so"); // explicit path services.AddFoundationDb(740, options => options.UseSystemNativeClient()); // OS search, with its risk ``` Without dependency injection, `Fdb.Options.SetNativeLibPath(path)` sets the path. **Network options** (for example the directory of the other client versions of the multi-version client) are set where the provider is registered, and the Aspire `configureProvider` callback can call it too: ```csharp services.AddFoundationDb(740, options => options .SetNetworkOption(FdbNetworkOption.ExternalClientDirectory, "/opt/foundationdb/clients") ); ``` They apply in the order of the calls, after the trace and TLS options. The network thread starts once per process, so the options of the **first** provider that starts apply to the whole process. --- ## 6. Client ⇄ cluster version compatibility (the silent hang) The **client library version must be compatible with the cluster version.** A 7.3 client **cannot** talk to a 7.4 cluster. - Symptom: transactions **hang** (no exception); `fdbcli` against the cluster reports *"One or more processes … incompatible"* and *"database is unavailable"*, even though the cluster is internally healthy. - Fix: make the AppHost `clusterVersion` (the Docker image tag) match the `libfdb_c` available to the app. Check the client with `fdbcli --version`, the server with `docker exec <container> fdbcli --version`. If you did not pin a tag, the mismatch is almost always a **system** `libfdb_c` shadowing the redistributed one (see §5), not the container. - The `apiVersion` (e.g. `730`) must be ≤ the cluster's supported level; `730` ⇒ 7.3, `740` ⇒ 7.4. For talking to **multiple** cluster versions from one process, FoundationDB's multi-version client loads several external `libfdb_c` libraries — but the simplest demo/dev setup is: one cluster version, one matching client library. --- ## 7. Golden rules & gotchas ✅ **DO** - Pick the provider source by context: Aspire client integration under an AppHost; plain `services.AddFoundationDb(...)` / `FdbDatabaseProvider.Create(...)` otherwise. - Launch the AppHost with `aspire run`; keep a `launchSettings.json` only as the `dotnet run`/F5 fallback. - Keep the cluster image and the client library on the **same major.minor** (7.4 with 7.4). Omitting `clusterVersion` lets the hosting package pair them for you against the `libfdb_c` that `FoundationDB.Client.Native` redistributes; pin it only when you supply your own client library, and then verify both with `fdbcli --version`. - On macOS, the redistributed client covers `osx-arm64` and `osx-x64` (since 7.4.6), so `UseNativeClient(allowSystemFallback: false)` works; fall back to a system `libfdb_c.dylib` and `allowSystemFallback: true` only for an older pin without your RID. ⚠️ **GOTCHAS** - **Transactions that hang on a brand-new cluster** are almost always a client/cluster **version mismatch**, not a deadlock — check versions first. - **`DllNotFoundException: fdb_c`** ⇒ none of the fixed paths holds the native client; the message lists them. Add `FoundationDB.Client.Native` with the major.minor of the cluster, or set `NativeLibraryPath` (see §5). A library only found through `PATH` or `LD_LIBRARY_PATH` is no longer loaded by default. - **AppHost `dotnet run` crash about ASPNETCORE_URLS / OTLP** ⇒ missing `launchSettings.json`, or just use `aspire run`. - **`AddFoundationDb` "ambiguous" / wrong overload** ⇒ you imported the wrong namespace; the AppHost call is on `IDistributedApplicationBuilder` (`Aspire.Hosting`), the client call on `IHostApplicationBuilder` (`Microsoft.Extensions.Hosting`). - `WithLifetime(ContainerLifetime.Persistent)` keeps the cluster's data across runs — handy in dev, but remember to `docker rm -f` it when you want a clean slate. --- ## 8. File map | What | Where | |---|---| | Aspire AppHost integration | `FoundationDB.Aspire.Hosting/FdbAspireHostingExtensions.cs` (`AddFoundationDb`, `AddFoundationDbCluster`, `FdbVersionPolicy`) | | Aspire client integration | `FoundationDB.Aspire/FdbAspireComponentExtensions.cs` (`AddFoundationDb`), `FdbClientSettings.cs` | | Plain DI / no-DI provider | `FoundationDB.Client/DependencyInjection/FdbDatabaseServiceCollectionExtensions.cs`, `Implementation/FdbDatabaseProvider.cs` | | Native client loader | `FoundationDB.Client.Native/` (`FdbClientNativeExtensions.cs` → `UseNativeClient`; `runtimes/` holds the shipped libs) |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.