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 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 han
SnowBankSDK · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add SnowBankSDK/foundationdb-dotnet-client --skill foundationdb-aspire技能说明
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:
// 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.FdbVersionPolicy(Exact, etc.) lives inAspire.Hosting.ApplicationModel..WithDefaults(timeout, retryLimit, tracing)tunes the connection.
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