foundationdb-dotnet-skills

FoundationDB .NET Client

C#/.NET binding for the FoundationDB client library.

How to use

To get started, install the FoundationDB.Client package into your application.

dotnet add package FoundationDB.Client

You will also probably require the FoundationDB.Client.Native package that redistributes the native FoundationDB Client libraries for your platform: fdb_c.dll on Windows, libfdb_c.so on Linux, and libfdb_c.dylib on macOS. They are available for x64 and arm64.

dotnet add package FoundationDB.Client.Native

For local development, you can use .NET Aspire to quickly spin up a working environment using a locally hosted Docker container.

Note: Using .NET Aspire for local development requires Docker Desktop on Windows.

Using Dependency Injection

While you can use the binding without dependency injection, it is very easy to register the IFdbDatabaseProvider service with the DI container and inject it into any controller, razor page, or other service that needs to query the database.

You can decide to manually configure the database connection, in which case you will need to provide a valid set of settings (API level, root path, ...) as well as copy a valid fdb.cluster file so that the process can connect to an existing FoundationDB cluster.

Alternatively, you can use the .NET Aspire integration to automatically setup a local FoundationDB Docker container, and inject the correct connection string.

Manual configuration

In your Program.cs, you should register FoundationDB with the DI container:

using FoundationDB.Client; // this is the main namespace of the library

var builder = WebApplication.CreateBuilder(args);

// ...

// Hook up FoundationDB types and interfaces to the DI container.
// You MUST select the appropriate API version that matches the target cluster.
// For example, '730' requires at least FoundationDB v7.3.x
builder.Services.AddFoundationDb(730, options =>
{
    // auto-start the connection to the cluster on the first request
    options.AutoStart = true; 

    // you can configure additional options here, like the path to the .cluster file, default timeouts, ...
});

var app = builder.Build();

// ...

// note: you don't need to configure anything for this step

app.Run();

This will register an instance of the IFdbDatabaseProvider singleton, that you can then inject into other types.

Using Aspire

It is possible to add a FoundationDB cluster resource to your Aspire application model, and pass a reference to this cluster to the projects that need it.

For this, you will need to install the following NuGet packages:

In the AppHost project:

dotnet add package FoundationDB.Aspire.Hosting

In each of the projects that need to connect to the FoundationDB cluster:

dotnet add package FoundationDB.Aspire

For local development, a local FoundationDB node will be started using the foundationdb/foundationdb Docker image, and all projects that use the cluster reference will have a temporary Cluster file pointing to the local instance.

Note: You must have Docker installed on your development machine. See the Aspire getting started guide for details.

In the Program.cs of your AppHost project:

private static void Main(string[] args)
{
    var builder = DistributedApplication.CreateBuilder(args);

    // Define a locally hosted FoundationDB cluster
    var fdb = builder
        .AddFoundationDb("fdb",
            apiVersion: 730,
            root: "/Tenant/ACME/MySuperApp/v1",
            clusterVersion: "7.4.6",
            rollForward: FdbVersionPolicy.Exact
         );

    // Project that needs a reference to this cluster
    var backend = builder
        .AddProject<Projects.AwesomeWebApiBackend>("backend")
        //...
        .WithReference(fdb); // register the fdb cluster connection