跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
部署与云服务

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:

WayAPIWhen
Plain DIservices.AddFoundationDb(apiVersion, opt => …) → IFdbDatabaseProviderBuilder (registers IFdbDatabaseProvider)a regular host, you supply the cluster file via config
No DIFdbDatabaseProvider.Create(new FdbDatabaseProviderOptions { ApiVersion = 730, … })tools/tests/standalone; call provider.Start()
Aspire clientbuilder.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 (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.
  • FdbVersionPolicy (Exact, etc.) lives in Aspire.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

阅读完整来源 ↗